HTTPRequest

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

A node with the ability to send HTTP requests. Uses 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:

Example of loading and displaying an image using HTTPRequest:

    # 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 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.

Note: SSL/TLS support is currently limited to TLS 1.0, TLS 1.1, and TLS 1.2. Attempting to connect to a TLS 1.3-only server will return an error.

Tutorials

• SSL certificates

Methods

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

Enumerations

enum Result:

• RESULT_SUCCESS = 0 —- Request successful.
• RESULT_CHUNKED_BODY_SIZE_MISMATCH = 1
• 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 .
• 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

• body_size_limit

Maximum allowed size for response bodies.

• int download_chunk_size

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

Set this to a lower value (e.g. 4096 for 4 KiB) when downloading small files to decrease memory usage at the cost of download speeds.

• String download_file

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

• max_redirects

Maximum number of allowed redirects.

• int timeout

• use_threads

If true, multithreading is used to improve performance.

Method Descriptions

• void cancel_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.

• get_downloaded_bytes ( ) const

Returns the amount of bytes this HTTPRequest downloaded.

Returns the current status of the underlying HTTPClient. See .

• Error request ( url, PoolStringArray custom_headers=PoolStringArray( ), ssl_validate_domain=true, Method method=0, request_data=”” )

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

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

Note: The parameter is ignored if method is . 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.