Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

HTTPClient

Inherits: RefCounted < Object

Low-level hyper-text transfer protocol client.

Description

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 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 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 TLS 1.0, TLS 1.1, and TLS 1.2. Attempting to connect to a TLS 1.3-only server 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.

Tutorials

Properties

bool

blocking_mode_enabled

false

StreamPeer

connection

int

read_chunk_size

65536

Methods

void

close ( )

Error

connect_to_host ( String host, int port=-1, TLSOptions tls_options=null )

int

get_response_body_length ( ) const

int

get_response_code ( ) const

PackedStringArray

get_response_headers ( )

Dictionary

get_response_headers_as_dictionary ( )

Status

get_status ( ) const

bool

has_response ( ) const

bool

is_response_chunked ( ) const

Error

poll ( )

String

query_string_from_dict ( Dictionary fields )

PackedByteArray

read_response_body_chunk ( )

Error

request ( Method method, String url, PackedStringArray headers, String body="" )

Error

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

void

set_http_proxy ( String host, int port )

void

set_https_proxy ( String host, int port )


Enumerations

enum Method:

Method METHOD_GET = 0

HTTP GET method. The GET method requests a representation of the specified resource. Requests using GET should only retrieve data.

Method METHOD_HEAD = 1

HTTP HEAD method. The HEAD method asks for a response identical to that of a GET request, but without the response body. This is useful to request metadata like HTTP headers or to check if a resource exists.

Method METHOD_POST = 2

HTTP POST method. The POST method is used to submit an entity to the specified resource, often causing a change in state or side effects on the server. This is often used for forms and submitting data or uploading files.

Method METHOD_PUT = 3

HTTP PUT method. The PUT method asks to replace all current representations of the target resource with the request payload. (You can think of POST as "create or update" and PUT as "update", although many services tend to not make a clear distinction or change their meaning).

Method METHOD_DELETE = 4

HTTP DELETE method. The DELETE method requests to delete the specified resource.