Class HTTPClient

Low-level hyper-text transfer protocol client.

Inheritance

RefCounted

Object

HTTPClient

Remarks

Hyper-text transfer protocol client (sometimes called "User Agent"). Used to make HTTP requests to download web content, upload files and other data or to communicate with various services, among other use cases.

See the HTTPRequest node for a higher-level alternative.

Note: This client only needs to connect to a host once (see HTTPClient.connect_to_host) to send multiple requests. Because of this, methods that take URLs usually take just the part after the host instead of the full URL, as the client is already connected to a host. See HTTPClient.request for a full example and to get started.

A HTTPClient should be reused between multiple requests or to connect to different hosts instead of creating one client per request. Supports Transport Layer Security (TLS), including server certificate verification. HTTP status codes in the 2xx range indicate success, 3xx redirection (i.e. "try again, but over here"), 4xx something was wrong with the request, and 5xx something went wrong on the server's side.

For more information on HTTP, see MDN's documentation on HTTP (or read RFC 2616 to get it straight from the source).

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.

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.

Note: When performing HTTP requests from a project exported to Web, 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: TLS support is currently limited to TLSv1.2 and TLSv1.3. Attempting to connect to a server that only supports older (insecure) TLS versions will return an error.

Warning: TLS certificate revocation and certificate pinning are currently not supported. Revoked certificates are accepted as long as they are otherwise valid. If this is a concern, you may want to use automatically managed certificates with a short validity period.

See Also

HTTP client class

TLS certificates

Properties

blocking_mode_enabled

If true, execution will block until all data is read from the response.

var blocking_mode_enabled : bool = false

Property Value

bool

Remarks

• void set_blocking_mode(bool value)
• bool is_blocking_mode_enabled

connection

The connection to use for this client.

var connection : StreamPeer

Property Value

StreamPeer

Remarks

• void set_connection(StreamPeer value)
• StreamPeer get_connection

read_chunk_size

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

var read_chunk_size : int = 65536

Property Value

int

Remarks

• void set_read_chunk_size(int value)
• int get_read_chunk_size

Methods

close

Closes the current connection, allowing reuse of this HTTPClient.

void close

connect_to_host(String, int, TLSOptions)

Connects to a host. This needs to be done before any requests are sent.

If no port is specified (or -1 is used), it is automatically set to 80 for HTTP and 443 for HTTPS. You can pass the optional tls_options parameter to customize the trusted certification authorities, or the common name verification when using HTTPS. See TLSOptions.client and TLSOptions.client_unsafe.

int connect_to_host(String host, int port, TLSOptions tls_options)

Parameters

host String

port int

tls_options TLSOptions

get_response_body_length

Qualifiers: const

Returns the response's 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.

Note: This function always returns -1 on the Web platform due to browsers limitations.

int get_response_body_length

get_response_code

Qualifiers: const

Returns the response's HTTP status code.

int get_response_code

get_response_headers

Returns the response headers.

PackedStringArray get_response_headers

get_response_headers_as_dictionary

Returns all response headers as a Dictionary. Each entry is composed by the header name, and a String containing the values separated by "; ". The casing is kept the same as the headers were received.

{
    "content-length": 12,
    "Content-Type": "application/json; charset=UTF-8",

}

Dictionary get_response_headers_as_dictionary

get_status

Qualifiers: const

Returns a Status constant. Need to call poll in order to get status updates.

int get_status

has_response

Qualifiers: const

If true, this HTTPClient has a response available.

bool has_response

is_response_chunked

Qualifiers: const

If true, this HTTPClient has a response that is chunked.

bool is_response_chunked

poll

This needs to be called in order to have any request processed. Check results with get_status.

int poll

query_string_from_dict(Dictionary)

Generates a GET/POST application/x-www-form-urlencoded style query string from a provided dictionary, e.g.:

• gdscript
• C#

var fields = {"username": "user", "password": "pass"}
var query_string = http_client.query_string_from_dict(fields)
# Returns "username=user&password=pass"

Furthermore, if a key has a null value, only the key itself is added, without equal sign and value. If the value is an array, for each value in it a pair with the same key is added.

• gdscript
• C#

var fields = {"single": 123, "not_valued": null, "multiple": [22, 33, 44]}
var query_string = http_client.query_string_from_dict(fields)
# Returns "single=123&not_valued&multiple=22&multiple=33&multiple=44"

String query_string_from_dict(Dictionary fields)

Parameters

fields Dictionary

read_response_body_chunk

Reads one chunk from the response.

PackedByteArray read_response_body_chunk

request(int, String, PackedStringArray, String)

Sends a request to the connected host.

The URL parameter is usually just the part after the host, so for https://example.com/index.php, it is /index.php. When sending requests to an HTTP proxy server, it should be an absolute URL. For HTTPClient.METHOD_OPTIONS requests, * is also allowed. For HTTPClient.METHOD_CONNECT requests, it should be the authority component (host:port).

Headers are HTTP request headers. For available HTTP methods, see Method.

To create a POST request with query strings to push to the server, do:

• gdscript
• C#

var fields = {"username" : "user", "password" : "pass"}
var query_string = http_client.query_string_from_dict(fields)
var headers = ["Content-Type: application/x-www-form-urlencoded", "Content-Length: " + str(query_string.length())]
var result = http_client.request(http_client.METHOD_POST, "/index.php", headers, query_string)

Note: The body parameter is ignored if method is HTTPClient.METHOD_GET. 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 uri_encode for an example.

int request(int method, String url, PackedStringArray headers, String body)

Parameters

method int

url String

headers PackedStringArray

body String

request_raw(int, String, PackedStringArray, PackedByteArray)

Sends a raw request to the connected host.

The URL parameter is usually just the part after the host, so for https://example.com/index.php, it is /index.php. When sending requests to an HTTP proxy server, it should be an absolute URL. For HTTPClient.METHOD_OPTIONS requests, * is also allowed. For HTTPClient.METHOD_CONNECT requests, it should be the authority component (host:port).

Headers are HTTP request headers. For available HTTP methods, see Method.

Sends the body data raw, as a byte array and does not encode it in any way.

int request_raw(int method, String url, PackedStringArray headers, PackedByteArray body)

Parameters

method int

url String

headers PackedStringArray

body 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