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.

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):
    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

Tutorials

Properties

int

body_size_limit

-1

int

download_chunk_size

65536

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="" )

Error

request_raw ( String url, PoolStringArray custom_headers=PoolStringArray( ), bool ssl_validate_domain=true, Method method=0, PoolByteArray request_data_raw=PoolByteArray( ) )

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_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

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.http_escape for an example.


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.