Class HTTPRequest

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

Inheritance: Node

Object

HTTPRequest

Remarks

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 TLS 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: Contact a REST API and print one of its returned fields:

gdscript
C#

func _ready():
    # Create an HTTP request node and connect its completion signal.
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(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 = JSON.new().stringify({"name": "Godette"})
    error = http_request.request("https://httpbin.org/post", [], 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 json = JSON.new()
    json.parse(body.get_string_from_utf8())
    var response = json.get_data()

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

public override void _Ready()
{
    // Create an HTTP request node and connect its completion signal.
    var httpRequest = new HttpRequest();
    AddChild(httpRequest);
    httpRequest.RequestCompleted += HttpRequestCompleted;

    // Perform a GET request. The URL below returns JSON as of writing.
    Error error = httpRequest.Request("https://httpbin.org/get");
    if (error != Error.Ok)
    {
        GD.PushError("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.
    string body = new Json().Stringify(new Godot.Collections.Dictionary
    {
        { "name", "Godette" }
    });
    error = httpRequest.Request("https://httpbin.org/post", null, HttpClient.Method.Post, body);
    if (error != Error.Ok)
    {
        GD.PushError("An error occurred in the HTTP request.");
    }
}

// Called when the HTTP request is completed.
private void HttpRequestCompleted(long result, long responseCode, string[] headers, byte[] body)
{
    var json = new Json();
    json.Parse(body.GetStringFromUtf8());
    var response = json.GetData().AsGodotDictionary();

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

}

Example: Load an image using HTTPRequest and display it:

gdscript
C#

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

    # Perform the HTTP request. The URL below returns a PNG image as of writing.
    var error = http_request.request("https://placehold.co/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.create_from_image(image)

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

public override void _Ready()
{
    // Create an HTTP request node and connect its completion signal.
    var httpRequest = new HttpRequest();
    AddChild(httpRequest);
    httpRequest.RequestCompleted += HttpRequestCompleted;

    // Perform the HTTP request. The URL below returns a PNG image as of writing.
    Error error = httpRequest.Request("https://placehold.co/512");
    if (error != Error.Ok)
    {
        GD.PushError("An error occurred in the HTTP request.");
    }
}

// Called when the HTTP request is completed.
private void HttpRequestCompleted(long result, long responseCode, string[] headers, byte[] body)
{
    if (result != (long)HttpRequest.Result.Success)
    {
        GD.PushError("Image couldn't be downloaded. Try a different image.");
    }
    var image = new Image();
    Error error = image.LoadPngFromBuffer(body);
    if (error != Error.Ok)
    {
        GD.PushError("Couldn't load the image.");
    }

    var texture = ImageTexture.CreateFromImage(image);

    // Display the image in a TextureRect node.
    var textureRect = new TextureRect();
    AddChild(textureRect);
    textureRect.Texture = texture;

}

Note: HTTPRequest nodes 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.

Properties

accept_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 HTTPRequest.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 HTTPRequest.request_completed.

var accept_gzip : bool = true

Property Value

bool

Remarks

void set_accept_gzip(bool value)
bool is_accepting_gzip

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.

var body_size_limit : int = -1

Property Value

int

Remarks

void set_body_size_limit(int value)
int get_body_size_limit

download_chunk_size

The size of the buffer used and maximum bytes to read per iteration. See 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.

var download_chunk_size : int = 65536

Property Value

int

Remarks

void set_download_chunk_size(int value)
int get_download_chunk_size

download_file

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

var download_file : String = ""

Property Value

String

Remarks

void set_download_file(String value)
String get_download_file

max_redirects

Maximum number of allowed redirects.

var max_redirects : int = 8

Property Value

int

Remarks

void set_max_redirects(int value)
int get_max_redirects

timeout

The duration to wait in seconds before a request times out. If timeout is set to 0.0 then the request will never time out. For simple requests, such as communication with a REST API, it is recommended that timeout is set to a value suitable for the server response time (e.g. between 1.0 and 10.0). This will help prevent unwanted timeouts caused by variation in server response times while still allowing the application to detect when a request has timed out. For larger requests such as file downloads it is suggested the timeout be set to 0.0, disabling the timeout functionality. This will help to prevent large transfers from failing due to exceeding the timeout value.

var timeout : float = 0.0

Property Value

float

Remarks

void set_timeout(float value)
float get_timeout

use_threads

If true, multithreading is used to improve performance.

var use_threads : bool = false

Property Value

bool

Remarks

void set_use_threads(bool value)
bool is_using_threads

Methods

cancel_request

Cancels the current request.

void cancel_request

get_body_size

Qualifiers: 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_body_size

get_downloaded_bytes

Qualifiers: const

Returns the number of bytes this HTTPRequest downloaded.

int get_downloaded_bytes

get_http_client_status

Qualifiers: const

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

int get_http_client_status

request(String, PackedStringArray, int, String)

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

Note: It's recommended to use transport encryption (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.

int request(String url, PackedStringArray custom_headers, int method, String request_data)

Parameters

url String
custom_headers PackedStringArray
method int
request_data String

request_raw(String, PackedStringArray, int, PackedByteArray)

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.

int request_raw(String url, PackedStringArray custom_headers, int method, PackedByteArray request_data_raw)

Parameters

url String
custom_headers PackedStringArray
method int
request_data_raw PackedByteArray

set_http_proxy(String, int)

Sets the proxy server for HTTP requests.

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

void set_http_proxy(String host, int port)

Parameters

host String
port int

set_https_proxy(String, int)

Sets the proxy server for HTTPS requests.

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

void set_https_proxy(String host, int port)

Parameters

host String
port int

set_tls_options(TLSOptions)

Sets the TLSOptions to be used when connecting to an HTTPS server. See TLSOptions.client.

void set_tls_options(TLSOptions client_options)

Parameters

client_options TLSOptions

Events

request_completed(int, int, PackedStringArray, PackedByteArray)

Emitted when a request is completed.

signal request_completed(int result, int response_code, PackedStringArray headers, PackedByteArray body)

Parameters

result int
response_code int
headers PackedStringArray
body PackedByteArray

Table of Contents

Class HTTPRequest

Remarks

See Also

Properties

accept_gzip

Property Value

Remarks

body_size_limit

Property Value

Remarks

download_chunk_size

Property Value

Remarks

download_file

Property Value

Remarks

max_redirects

Property Value

Remarks

timeout

Property Value

Remarks

use_threads

Property Value

Remarks

Methods

cancel_request

get_body_size

get_downloaded_bytes

get_http_client_status

request(String, PackedStringArray, int, String)

Parameters

request_raw(String, PackedStringArray, int, PackedByteArray)

Parameters

set_http_proxy(String, int)

Parameters

set_https_proxy(String, int)

Parameters

set_tls_options(TLSOptions)

Parameters

Events

request_completed(int, int, PackedStringArray, PackedByteArray)

Parameters