Difference between revisions of "Lua API:HTTP"
(Update as per commit afefd045) |
(98.0: Add header return value for HTTPRequest:finish, document new way of passing in post_data / headers to http.post) |
||
| (5 intermediate revisions by 2 users not shown) | |||
| Line 11: | Line 11: | ||
* "done" if the request has finished and the response body is ready to be read; | * "done" if the request has finished and the response body is ready to be read; | ||
* "dead" if the request is dead, i.e. if it has been cancelled or if the response body has been read. | * "dead" if the request is dead, i.e. if it has been cancelled or if the response body has been read. | ||
| + | |||
| + | Note that requests are not guaranteed to make any progress whatsoever if you keep calling this function in a blocking loop until it returns "done". The correct way to use this function is to call it once per tick (see [https://powdertoy.co.uk/Wiki/W/Lua_API:Event.html#Event_Types the tick event type]) or even less frequently. | ||
==== HTTPRequest:progress ==== | ==== HTTPRequest:progress ==== | ||
| Line 21: | Line 23: | ||
==== HTTPRequest:finish ==== | ==== HTTPRequest:finish ==== | ||
| − | string, number HTTPRequest:finish() | + | string, number, table HTTPRequest:finish() |
| − | Finishes the request and returns the response body | + | Finishes the request and returns the response body, status code, and headers. Call this only when HTTPRequest:status returns "done". Does and returns nothing if the request is dead. |
| + | |||
| + | Header data is returned as a collection of table objects. Each header is represented by a subtable t with t[1] containing the header name and t[2] containing the value. | ||
Non-standard status codes of note are 601, which is returned by plain HTTP requests if TPT is built with ENFORCE_HTTPS, and 604, which is returned by all requests if TPT is built with NOHTTP. Note that both codes may be returned for other reasons. | Non-standard status codes of note are 601, which is returned by plain HTTP requests if TPT is built with ENFORCE_HTTPS, and 604, which is returned by all requests if TPT is built with NOHTTP. Note that both codes may be returned for other reasons. | ||
| Line 29: | Line 33: | ||
=== http.get === | === http.get === | ||
| − | HTTPRequest http.get(string uri, [table headers]) | + | HTTPRequest http.get(string uri, [table headers], [string verb]) |
| − | Constructs an HTTPRequest object and starts the underlying GET request immediately with the URI and headers supplied. The optional | + | Constructs an HTTPRequest object and starts the underlying GET request immediately with the URI and headers supplied. The optional headers argument is a collection of string key and string value pairs. The optional verb argument will change this GET request into a custom request. |
| + | |||
| + | headers can also be given as a collection of table objects, where t[1] is the header name and t[2] is the value. | ||
=== http.post === | === http.post === | ||
| − | HTTPRequest http.post(string uri, table post_params, [table headers]) | + | HTTPRequest http.post(string uri, [table post_params | string post_data], [table headers], [string verb]) |
| − | Same as http.get, except the underlying request is a POST. Post parameters are passed in the extra table argument, a collection of string key and string value pairs. | + | Same as http.get, except the underlying request is a POST. Post parameters are passed in the extra table argument, a collection of string key and string value pairs. You can also pass in string data to make a non-multipart POST request, or omit the argument to make a POST request with no data. The optional verb argument will change this POST request into a custom request (such as DELETE, etc.). |
| + | |||
| + | post parameters and headers can also be given as a collection of table objects, where t[1] is the parameter name and t[2] is the value. For post parameters only, t[3] is optional and controls the filename. | ||
| + | |||
| + | === http.getAuthToken === | ||
| + | HTTPRequest http.getAuthToken(string audience) | ||
| + | Starts a request to retrieve an auth token, which can be used to authenticate with services such as tptmp that verify your TPT account, without needing a password or session key sharing. This is not useful to end users. | ||
Latest revision as of 21:26, 30 December 2023
The HTTP API provides access to basic HTTP functionality. Depending on how TPT is built, it may only work with secure sites (ones that use TLS, i.e. HTTPS) or it may even be wholly unable to actually complete HTTP requests; see relevant #defines in Config.h.
Contents
Classes
HTTPRequest
HTTPRequest:status
string HTTPRequest:status()
Returns one of the following:
- "running" if the request hasn't finished yet;
- "done" if the request has finished and the response body is ready to be read;
- "dead" if the request is dead, i.e. if it has been cancelled or if the response body has been read.
Note that requests are not guaranteed to make any progress whatsoever if you keep calling this function in a blocking loop until it returns "done". The correct way to use this function is to call it once per tick (see the tick event type) or even less frequently.
HTTPRequest:progress
number, number HTTPRequest:progress()
If the request is not dead, returns the size of the response body in bytes in the first return value (-1 if the size is not known), and the number of bytes received so far in the second. If the request is dead, returns nothing.
HTTPRequest:cancel
nil HTTPRequest:cancel()
Cancels the request. Does nothing if the request is dead.
HTTPRequest:finish
string, number, table HTTPRequest:finish()
Finishes the request and returns the response body, status code, and headers. Call this only when HTTPRequest:status returns "done". Does and returns nothing if the request is dead.
Header data is returned as a collection of table objects. Each header is represented by a subtable t with t[1] containing the header name and t[2] containing the value.
Non-standard status codes of note are 601, which is returned by plain HTTP requests if TPT is built with ENFORCE_HTTPS, and 604, which is returned by all requests if TPT is built with NOHTTP. Note that both codes may be returned for other reasons.
Methods
http.get
HTTPRequest http.get(string uri, [table headers], [string verb])
Constructs an HTTPRequest object and starts the underlying GET request immediately with the URI and headers supplied. The optional headers argument is a collection of string key and string value pairs. The optional verb argument will change this GET request into a custom request.
headers can also be given as a collection of table objects, where t[1] is the header name and t[2] is the value.
http.post
HTTPRequest http.post(string uri, [table post_params | string post_data], [table headers], [string verb])
Same as http.get, except the underlying request is a POST. Post parameters are passed in the extra table argument, a collection of string key and string value pairs. You can also pass in string data to make a non-multipart POST request, or omit the argument to make a POST request with no data. The optional verb argument will change this POST request into a custom request (such as DELETE, etc.).
post parameters and headers can also be given as a collection of table objects, where t[1] is the parameter name and t[2] is the value. For post parameters only, t[3] is optional and controls the filename.
http.getAuthToken
HTTPRequest http.getAuthToken(string audience)
Starts a request to retrieve an auth token, which can be used to authenticate with services such as tptmp that verify your TPT account, without needing a password or session key sharing. This is not useful to end users.
