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 godot.HTTPRequest node for a higher-level alternative.
Note: This client only needs to connect to a host once (see godot.HTTPClient.connectToHost) 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 godot.HTTPClient.request for a full example and to get started.
A godot.HTTPClient should be reused between multiple requests or to connect to different hosts instead of creating one client per request. Supports SSL and SSL 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 https://developer.mozilla.org/en-US/docs/Web/HTTP (or read RFC 2616 to get it straight from the source: https://tools.ietf.org/html/rfc2616).
Note: When performing HTTP requests from a project exported to HTML5, keep in mind the remote server may not allow requests from foreign origins due to [https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS](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: SSL/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: SSL/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.
Constructor
Variables
readChunkSize:Int
The size of the buffer used and maximum bytes to read per iteration. See godot.HTTPClient.readResponseBodyChunk.
Methods
connectToHost(host:String, ?port:Int, ?useSsl:Bool, ?verifyHost:Bool):Error
Connects to a host. This needs to be done before any requests are sent.
The host should not have http:// prepended but will strip the protocol identifier if provided.
If no port is specified (or -1 is used), it is automatically set to 80 for HTTP and 443 for HTTPS (if use_ssl is enabled).
verify_host will check the SSL identity of the host if set to true.
getResponseBodyLength():Int
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.
getResponseHeadersAsDictionary():Dictionary
Returns all response headers as a Dictionary of structure { "key": "value1; value2" } where the case-sensitivity of the keys and values is kept like the server delivers it. A value is a simple String, this string can have more than one value where "; " is used as separator.
Example:
{
"content-length": 12,
"Content-Type": "application/json; charset=UTF-8",
}
getStatus():HTTPClient_Status
Returns a godot.HTTPClient_Status constant. Need to call godot.HTTPClient.poll in order to get status updates.
poll():Error
This needs to be called in order to have any request processed. Check results with godot.HTTPClient.getStatus.
queryStringFromDict(fields:Dictionary):String
Generates a GET/POST application/x-www-form-urlencoded style query string from a provided dictionary, e.g.:
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.
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"
request(method:HTTPClient_Method, url:String, headers:Array<String>, ?body:String):Error
Sends a request to the connected host.
The URL parameter is usually just the part after the host, so for http://somehost.com/index.php, it is /index.php. When sending requests to an HTTP proxy server, it should be an absolute URL. For godot.HTTPClient_Method.options requests, * is also allowed. For godot.HTTPClient_Method.connect requests, it should be the authority component (host:port).
Headers are HTTP request headers. For available HTTP methods, see godot.HTTPClient_Method.
To create a POST request with query strings to push to the server, do:
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 request_data parameter is ignored if method is godot.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 String.http_escape for an example.
requestRaw(method:HTTPClient_Method, url:String, headers:HaxeArray<String>, body:HaxeArray<UInt8>):Error
Sends a raw request to the connected host.
The URL parameter is usually just the part after the host, so for http://somehost.com/index.php, it is /index.php. When sending requests to an HTTP proxy server, it should be an absolute URL. For godot.HTTPClient_Method.options requests, * is also allowed. For godot.HTTPClient_Method.connect requests, it should be the authority component (host:port).
Headers are HTTP request headers. For available HTTP methods, see godot.HTTPClient_Method.
Sends the body data raw, as a byte array and does not encode it in any way.