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 = to_json({"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

• Making HTTP requests

• SSL certificates

Properties

int	body_size_limit	-1
int	download_chunk_size	65536
String	download_file	""
int	max_redirects	8
float	timeout	0.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( ) )
void	set_http_proxy ( String host, int port )
void	set_https_proxy ( String host, int port )

---

Signals

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

Emitted when a request is completed.

---

Enumerations

enum Result:

Result RESULT_SUCCESS = 0

Request successful.

Result RESULT_CHUNKED_BODY_SIZE_MISMATCH = 1

Result RESULT_CANT_CONNECT = 2

Request failed while connecting.

Result RESULT_CANT_RESOLVE = 3

Request failed while resolving.

Result RESULT_CONNECTION_ERROR = 4

Request failed due to connection (read/write) error.

Result RESULT_SSL_HANDSHAKE_ERROR = 5

Request failed on SSL handshake.

Result RESULT_NO_RESPONSE = 6

Request does not have a response (yet).

Result RESULT_BODY_SIZE_LIMIT_EXCEEDED = 7

Request exceeded its maximum size limit, see body_size_limit.

Result RESULT_REQUEST_FAILED = 8

Request failed (currently unused).

Result RESULT_DOWNLOAD_FILE_CANT_OPEN = 9

HTTPRequest couldn't open the download file.

Result RESULT_DOWNLOAD_FILE_WRITE_ERROR = 10

HTTPRequest couldn't write to the download file.

Result RESULT_REDIRECT_LIMIT_REACHED = 11

Request reached its maximum redirect limit, see max_redirects.

Result RESULT_TIMEOUT = 12

---

Property Descriptions

int body_size_limit = -1

• void set_body_size_limit ( int value )

• int get_body_size_limit ( )

Maximum allowed size for response bodies (-1 means no limit). When only small files are expected, this can be used to prevent disallow receiving files that are too large, preventing potential denial of service attacks.

---

int download_chunk_size = 65536

• void set_download_chunk_size ( int value )

• int 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.

---

String download_file = ""

• void set_download_file ( String value )

• String get_download_file ( )

The file to download into. If set to a non-empty string, the request output will be written to the file located at the path. If a file already exists at the specified location, it will be overwritten as soon as body data begins to be received.

Note: Folders are not automatically created when the file is created. If download_file points to a subfolder, it's recommended to create the necessary folders beforehand using Directory.make_dir_recursive to ensure the file can be written.

---

int max_redirects = 8

• void set_max_redirects ( int value )

• int get_max_redirects ( )

Maximum number of allowed redirects. This is used to prevent endless redirect loops.

---

float timeout = 0.0

• void set_timeout ( float value )

• float get_timeout ( )

If set to a value greater than 0.0 before the request starts, the HTTP request will time out after timeout seconds have passed and the request is not completed yet. For small HTTP requests such as REST API usage, set timeout to a value between 10.0 and 30.0 to prevent the application from getting stuck if the request fails to get a response in a timely manner. For file downloads, leave this to 0.0 to prevent the download from failing if it takes too much time.

---

bool use_threads = false

• void set_use_threads ( bool value )

• bool 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: 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.

---

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

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.

---

void set_http_proxy ( String host, int port )

Sets the proxy server for HTTP requests.

The proxy server is unset if host is empty or port is -1.

---

void set_https_proxy ( String host, int port )

Sets the proxy server for HTTPS requests.

The proxy server is unset if host is empty or port is -1.