<?xml version="1.0" encoding="UTF-8" ?> <class name="HTTPRequest" inherits="Node" version="3.5"> <brief_description> A node with the ability to send HTTP(S) requests. </brief_description> <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. [b]Warning:[/b] See the notes and warnings on [HTTPClient] for limitations, especially regarding SSL security. [b]Example of contacting a REST API and printing one of its returned fields:[/b] [codeblock] 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"]) [/codeblock] [b]Example of loading and displaying an image using HTTPRequest:[/b] [codeblock] 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 [/codeblock] </description> <tutorials> <link>$DOCS_URL/tutorials/networking/http_request_class.html</link> <link>$DOCS_URL/tutorials/networking/ssl_certificates.html</link> </tutorials> <methods> <method name="cancel_request"> <return type="void" /> <description> Cancels the current request. </description> </method> <method name="get_body_size" qualifiers="const"> <return type="int" /> <description> Returns the response body length. [b]Note:[/b] Some Web servers may not send a body length. In this case, the value returned will be [code]-1[/code]. If using chunked transfer encoding, the body length will also be [code]-1[/code]. </description> </method> <method name="get_downloaded_bytes" qualifiers="const"> <return type="int" /> <description> Returns the amount of bytes this HTTPRequest downloaded. </description> </method> <method name="get_http_client_status" qualifiers="const"> <return type="int" enum="HTTPClient.Status" /> <description> Returns the current status of the underlying [HTTPClient]. See [enum HTTPClient.Status]. </description> </method> <method name="request"> <return type="int" enum="Error" /> <argument index="0" name="url" type="String" /> <argument index="1" name="custom_headers" type="PoolStringArray" default="PoolStringArray( )" /> <argument index="2" name="ssl_validate_domain" type="bool" default="true" /> <argument index="3" name="method" type="int" enum="HTTPClient.Method" default="0" /> <argument index="4" name="request_data" type="String" default="""" /> <description> Creates request on the underlying [HTTPClient]. If there is no configuration errors, it tries to connect using [method HTTPClient.connect_to_host] and passes parameters onto [method HTTPClient.request]. Returns [constant OK] if request is successfully created. (Does not imply that the server has responded), [constant ERR_UNCONFIGURED] if not in the tree, [constant ERR_BUSY] if still processing previous request, [constant ERR_INVALID_PARAMETER] if given string is not a valid URL format, or [constant ERR_CANT_CONNECT] if not using thread and the [HTTPClient] cannot connect to host. [b]Note:[/b] When [code]method[/code] is [constant HTTPClient.METHOD_GET], the payload sent via [code]request_data[/code] might be ignored by the server or even cause the server to reject the request (check [url=https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.1]RFC 7231 section 4.3.1[/url] for more details). As a workaround, you can send data as a query string in the URL. See [method String.http_escape] for an example. </description> </method> <method name="request_raw"> <return type="int" enum="Error" /> <argument index="0" name="url" type="String" /> <argument index="1" name="custom_headers" type="PoolStringArray" default="PoolStringArray( )" /> <argument index="2" name="ssl_validate_domain" type="bool" default="true" /> <argument index="3" name="method" type="int" enum="HTTPClient.Method" default="0" /> <argument index="4" name="request_data_raw" type="PoolByteArray" default="PoolByteArray( )" /> <description> 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 [method HTTPClient.connect_to_host] and passes parameters onto [method HTTPClient.request]. Returns [constant OK] if request is successfully created. (Does not imply that the server has responded), [constant ERR_UNCONFIGURED] if not in the tree, [constant ERR_BUSY] if still processing previous request, [constant ERR_INVALID_PARAMETER] if given string is not a valid URL format, or [constant ERR_CANT_CONNECT] if not using thread and the [HTTPClient] cannot connect to host. </description> </method> <method name="set_http_proxy"> <return type="void" /> <argument index="0" name="host" type="String" /> <argument index="1" name="port" type="int" /> <description> Sets the proxy server for HTTP requests. The proxy server is unset if [code]host[/code] is empty or [code]port[/code] is -1. </description> </method> <method name="set_https_proxy"> <return type="void" /> <argument index="0" name="host" type="String" /> <argument index="1" name="port" type="int" /> <description> Sets the proxy server for HTTPS requests. The proxy server is unset if [code]host[/code] is empty or [code]port[/code] is -1. </description> </method> </methods> <members> <member name="body_size_limit" type="int" setter="set_body_size_limit" getter="get_body_size_limit" default="-1"> Maximum allowed size for response bodies ([code]-1[/code] 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. </member> <member name="download_chunk_size" type="int" setter="set_download_chunk_size" getter="get_download_chunk_size" default="65536"> The size of the buffer used and maximum bytes to read per iteration. See [member 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. </member> <member name="download_file" type="String" setter="set_download_file" getter="get_download_file" default=""""> 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. [b]Note:[/b] Folders are not automatically created when the file is created. If [member download_file] points to a subfolder, it's recommended to create the necessary folders beforehand using [method Directory.make_dir_recursive] to ensure the file can be written. </member> <member name="max_redirects" type="int" setter="set_max_redirects" getter="get_max_redirects" default="8"> Maximum number of allowed redirects. This is used to prevent endless redirect loops. </member> <member name="timeout" type="float" setter="set_timeout" getter="get_timeout" default="0.0"> If set to a value greater than [code]0.0[/code] before the request starts, the HTTP request will time out after [code]timeout[/code] seconds have passed and the request is not [i]completed[/i] yet. For small HTTP requests such as REST API usage, set [member timeout] to a value between [code]10.0[/code] and [code]30.0[/code] 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 [code]0.0[/code] to prevent the download from failing if it takes too much time. </member> <member name="use_threads" type="bool" setter="set_use_threads" getter="is_using_threads" default="false"> If [code]true[/code], multithreading is used to improve performance. </member> </members> <signals> <signal name="request_completed"> <argument index="0" name="result" type="int" /> <argument index="1" name="response_code" type="int" /> <argument index="2" name="headers" type="PoolStringArray" /> <argument index="3" name="body" type="PoolByteArray" /> <description> Emitted when a request is completed. </description> </signal> </signals> <constants> <constant name="RESULT_SUCCESS" value="0" enum="Result"> Request successful. </constant> <constant name="RESULT_CHUNKED_BODY_SIZE_MISMATCH" value="1" enum="Result"> </constant> <constant name="RESULT_CANT_CONNECT" value="2" enum="Result"> Request failed while connecting. </constant> <constant name="RESULT_CANT_RESOLVE" value="3" enum="Result"> Request failed while resolving. </constant> <constant name="RESULT_CONNECTION_ERROR" value="4" enum="Result"> Request failed due to connection (read/write) error. </constant> <constant name="RESULT_SSL_HANDSHAKE_ERROR" value="5" enum="Result"> Request failed on SSL handshake. </constant> <constant name="RESULT_NO_RESPONSE" value="6" enum="Result"> Request does not have a response (yet). </constant> <constant name="RESULT_BODY_SIZE_LIMIT_EXCEEDED" value="7" enum="Result"> Request exceeded its maximum size limit, see [member body_size_limit]. </constant> <constant name="RESULT_REQUEST_FAILED" value="8" enum="Result"> Request failed (currently unused). </constant> <constant name="RESULT_DOWNLOAD_FILE_CANT_OPEN" value="9" enum="Result"> HTTPRequest couldn't open the download file. </constant> <constant name="RESULT_DOWNLOAD_FILE_WRITE_ERROR" value="10" enum="Result"> HTTPRequest couldn't write to the download file. </constant> <constant name="RESULT_REDIRECT_LIMIT_REACHED" value="11" enum="Result"> Request reached its maximum redirect limit, see [member max_redirects]. </constant> <constant name="RESULT_TIMEOUT" value="12" enum="Result"> </constant> </constants> </class>