HTTPRequest

Inherits: Node < Object

A node with the ability to send HTTP(S) requests.

Description

A node with the ability to send HTTP requests. Uses HTTPClient internally.

Can be used to make HTTP requests, i.e. download or upload files or web content via HTTP.

Example of contacting a REST API and printing one of its returned fields:

func _ready():
    # Create an HTTP request node and connect its completion signal.
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.connect("request_completed", self, "_http_request_completed")

    # Perform a GET request. The URL below returns JSON as of writing.
    var error = http_request.request("https://httpbin.org/get")
    if error != OK:
        push_error("An error occurred in the HTTP request.")

    # Perform a POST request. The URL below returns JSON as of writing.
    # Note: Don't make simultaneous requests using a single HTTPRequest node.
    # The snippet below is provided for reference only.
    var body = {"name": "Godette"}
    var error = http_request.request("https://httpbin.org/post", [], true, HTTPClient.METHOD_POST, body)
    if error != OK:
        push_error("An error occurred in the HTTP request.")


# Called when the HTTP request is completed.
func _http_request_completed(result, response_code, headers, body):
    var response = parse_json(body.get_string_from_utf8())

    # Will print the user agent string used by the HTTPRequest node (as recognized by httpbin.org).
    print(response.headers["User-Agent"])

Example of loading and displaying an image using HTTPRequest:

func _ready():
    # Create an HTTP request node and connect its completion signal.
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.connect("request_completed", self, "_http_request_completed")

    # Perform the HTTP request. The URL below returns a PNG image as of writing.
    var error = http_request.request("https://via.placeholder.com/512")
    if error != OK:
        push_error("An error occurred in the HTTP request.")


# Called when the HTTP request is completed.
func _http_request_completed(result, response_code, headers, body):
    var image = Image.new()
    var error = image.load_png_from_buffer(body)
    if error != OK:
        push_error("Couldn't load the image.")

    var texture = ImageTexture.new()
    texture.create_from_image(image)

    # Display the image in a TextureRect node.
    var texture_rect = TextureRect.new()
    add_child(texture_rect)
    texture_rect.texture = texture

Note: When performing HTTP requests from a project exported to HTML5, keep in mind the remote server may not allow requests from foreign origins due to CORS. If you host the server in question, you should modify its backend to allow requests from foreign origins by adding the Access-Control-Allow-Origin: * HTTP header.

Tutorials

• Making HTTP requests
• SSL certificates

Properties

int	body_size_limit	-1
int	download_chunk_size	4096
String	download_file	""
int	max_redirects	8
int	timeout	0
bool	use_threads	false

Methods

void	cancel_request ( )
int	get_body_size ( ) const
int	get_downloaded_bytes ( ) const
Status	get_http_client_status ( ) const
Error	request ( String url, PoolStringArray custom_headers=PoolStringArray( ), bool ssl_validate_domain=true, Method method=0, String request_data="" )

Signals

request_completed ( int result, int response_code, PoolStringArray headers, PoolByteArray body )

Emitted when a request is completed.

Enumerations

enum Result:

• RESULT_SUCCESS = 0 --- Request successful.
• RESULT_CHUNKED_BODY_SIZE_MISMATCH = 1
• RESULT_CANT_CONNECT = 2 --- Request failed while connecting.
• RESULT_CANT_RESOLVE = 3 --- Request failed while resolving.
• RESULT_CONNECTION_ERROR = 4 --- Request failed due to connection (read/write) error.
• RESULT_SSL_HANDSHAKE_ERROR = 5 --- Request failed on SSL handshake.
• RESULT_NO_RESPONSE = 6 --- Request does not have a response (yet).
• RESULT_BODY_SIZE_LIMIT_EXCEEDED = 7 --- Request exceeded its maximum size limit, see body_size_limit.
• RESULT_REQUEST_FAILED = 8 --- Request failed (currently unused).
• RESULT_DOWNLOAD_FILE_CANT_OPEN = 9 --- HTTPRequest couldn't open the download file.
• RESULT_DOWNLOAD_FILE_WRITE_ERROR = 10 --- HTTPRequest couldn't write to the download file.
• RESULT_REDIRECT_LIMIT_REACHED = 11 --- Request reached its maximum redirect limit, see max_redirects.
• RESULT_TIMEOUT = 12

Property Descriptions

int body_size_limit

Default	-1
Setter	set_body_size_limit(value)
Getter	get_body_size_limit()

Maximum allowed size for response bodies.

int download_chunk_size

Default	4096
Setter	set_download_chunk_size(value)
Getter	get_download_chunk_size()

The size of the buffer used and maximum bytes to read per iteration. See HTTPClient.read_chunk_size.

Set this to a higher value (e.g. 65536 for 64 KiB) when downloading large files to achieve better speeds at the cost of memory.

String download_file

Default	""
Setter	set_download_file(value)
Getter	get_download_file()

The file to download into. Will output any received file into it.

int max_redirects

Default	8
Setter	set_max_redirects(value)
Getter	get_max_redirects()

Maximum number of allowed redirects.

int timeout

Default	0
Setter	set_timeout(value)
Getter	get_timeout()

bool use_threads

Default	false
Setter	set_use_threads(value)
Getter	is_using_threads()

If true, multithreading is used to improve performance.

Method Descriptions

void cancel_request ( )

Cancels the current request.

int get_body_size ( ) const

Returns the response body length.

Note: Some Web servers may not send a body length. In this case, the value returned will be -1. If using chunked transfer encoding, the body length will also be -1.

int get_downloaded_bytes ( ) const

Returns the amount of bytes this HTTPRequest downloaded.

Status get_http_client_status ( ) const

Returns the current status of the underlying HTTPClient. See Status.

Error request ( String url, PoolStringArray custom_headers=PoolStringArray( ), bool ssl_validate_domain=true, Method method=0, String request_data="" )

Creates request on the underlying HTTPClient. If there is no configuration errors, it tries to connect using HTTPClient.connect_to_host and passes parameters onto HTTPClient.request.

Returns @GlobalScope.OK if request is successfully created. (Does not imply that the server has responded), @GlobalScope.ERR_UNCONFIGURED if not in the tree, @GlobalScope.ERR_BUSY if still processing previous request, @GlobalScope.ERR_INVALID_PARAMETER if given string is not a valid URL format, or @GlobalScope.ERR_CANT_CONNECT if not using thread and the HTTPClient cannot connect to host.

Note: The request_data parameter is ignored if method is HTTPClient.METHOD_GET. This is because GET methods can't contain request data. As a workaround, you can pass request data as a query string in the URL. See String.http_escape for an example.