summaryrefslogtreecommitdiff
path: root/doc/classes
diff options
context:
space:
mode:
authorHugo Locurcio <hugo.locurcio@hugo.pro>2020-08-03 14:56:53 +0200
committerHugo Locurcio <hugo.locurcio@hugo.pro>2020-08-03 14:57:27 +0200
commit2f577facc9ee30895e80b6069bdd4d803edd406c (patch)
treea8cc96d26b0bc9b123c34494d8c48847bfe4bfc7 /doc/classes
parent9adf6d3441d4927bdbab7bcb03cfafe42249ba90 (diff)
Document HTTPRequest not supporting request data with GET method
This also improves the HTTPClient class documentation to be easier to read and more informative. This closes #40564.
Diffstat (limited to 'doc/classes')
-rw-r--r--doc/classes/HTTPClient.xml5
-rw-r--r--doc/classes/HTTPRequest.xml1
2 files changed, 4 insertions, 2 deletions
diff --git a/doc/classes/HTTPClient.xml b/doc/classes/HTTPClient.xml
index 7e8f0807ac..663638d1b6 100644
--- a/doc/classes/HTTPClient.xml
+++ b/doc/classes/HTTPClient.xml
@@ -1,10 +1,10 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="HTTPClient" inherits="Reference" version="4.0">
<brief_description>
- Hyper-text transfer protocol client.
+ Low-level hyper-text transfer protocol client.
</brief_description>
<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 [HTTPRequest] for an higher-level alternative.
+ 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. [b]See the [HTTPRequest] node for an higher-level alternative.[/b]
[b]Note:[/b] This client only needs to connect to a host once (see [method 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 [method 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 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).
@@ -152,6 +152,7 @@
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)
[/codeblock]
+ [b]Note:[/b] The [code]request_data[/code] parameter is ignored if [code]method[/code] is [constant 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 [method String.http_escape] for an example.
</description>
</method>
<method name="request_raw">
diff --git a/doc/classes/HTTPRequest.xml b/doc/classes/HTTPRequest.xml
index 61e0d2e2b9..338534fe49 100644
--- a/doc/classes/HTTPRequest.xml
+++ b/doc/classes/HTTPRequest.xml
@@ -116,6 +116,7 @@
<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] The [code]request_data[/code] parameter is ignored if [code]method[/code] is [constant 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 [method String.http_escape] for an example.
</description>
</method>
</methods>