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.

Warning: See the notes and warnings on HTTPClient for limitations, especially regarding SSL security.

Note: When exporting to Android, make sure to enable the INTERNET permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android.

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"}
    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):
    if result != HTTPRequest.RESULT_SUCCESS:
        push_error("Image couldn't be downloaded. Try a different image.")

    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

Gzipped response bodies: HTTPRequest will automatically handle decompression of response bodies. A Accept-Encoding header will be automatically added to each of your requests, unless one is already specified. Any response with a Content-Encoding: gzip header will automatically be decompressed and delivered to you as uncompressed bytes.

Methods

void

cancel_request ( )

int

get_body_size ( ) const

int

get_downloaded_bytes ( ) const

Status

get_http_client_status ( ) const

Error

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

Error

request_raw ( String url, PackedStringArray custom_headers=PackedStringArray(), bool ssl_validate_domain=true, Method method=0, PackedByteArray request_data_raw=PackedByteArray() )

Signals

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_BODY_DECOMPRESS_FAILED = 8

  • RESULT_REQUEST_FAILED = 9 --- Request failed (currently unused).

  • RESULT_DOWNLOAD_FILE_CANT_OPEN = 10 --- HTTPRequest couldn't open the download file.

  • RESULT_DOWNLOAD_FILE_WRITE_ERROR = 11 --- HTTPRequest couldn't write to the download file.

  • RESULT_REDIRECT_LIMIT_REACHED = 12 --- Request reached its maximum redirect limit, see max_redirects.

  • RESULT_TIMEOUT = 13

Property Descriptions

Default

true

Setter

set_accept_gzip(value)

Getter

is_accepting_gzip()

If true, this header will be added to each request: Accept-Encoding: gzip, deflate telling servers that it's okay to compress response bodies.

Any Response body declaring a Content-Encoding of either gzip or deflate will then be automatically decompressed, and the uncompressed bytes will be delivered via request_completed.

If the user has specified their own Accept-Encoding header, then no header will be added regardless of accept_gzip.

If false no header will be added, and no decompression will be performed on response bodies. The raw bytes of the response body will be returned via request_completed.


  • int body_size_limit

Default

-1

Setter

set_body_size_limit(value)

Getter

get_body_size_limit()

Maximum allowed size for response bodies. If the response body is compressed, this will be used as the maximum allowed size for the decompressed body.


  • int download_chunk_size

Default

65536

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 lower value (e.g. 4096 for 4 KiB) when downloading small files to decrease memory usage at the cost of download speeds.


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.


Default

0

Setter

set_timeout(value)

Getter

get_timeout()


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.


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: When method is HTTPClient.METHOD_GET, the payload sent via request_data might be ignored by the server or even cause the server to reject the request (check RFC 7231 section 4.3.1 for more details). As a workaround, you can send data as a query string in the URL (see String.uri_encode for an example).

Note: It's recommended to use transport encryption (SSL/TLS) and to avoid sending sensitive information (such as login credentials) in HTTP GET URL parameters. Consider using HTTP POST requests or HTTP headers for such information instead.


Creates request on the underlying HTTPClient using a raw array of bytes for the request body. 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.