Difference between revisions of "Lua API:HTTP"

From The Powder Toy
Jump to: navigation, search
(Add HTTP API page)
 
m (Explain how the API determines whether to initiate a POST or a GET request)
Line 29: Line 29:
 
=== http.request ===
 
=== http.request ===
 
  HTTPRequest http.request(string uri, [table post_params, [table headers]])
 
  HTTPRequest http.request(string uri, [table post_params, [table headers]])
Constructs a HTTPRequest object and starts the underlying request immediately with the URI, post parameters and headers supplied. Both optional tables are collections of string key and string value pairs.
+
Constructs a HTTPRequest object and starts the underlying request immediately with the URI, post parameters and headers supplied. Both optional tables are collections of string key and string value pairs. The request is a POST if post parameters are supplied, a GET otherwise.

Revision as of 21:25, 16 January 2020

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 not even be available.

assert(http, "HTTP functionality unavailable")

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.

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 HTTPRequest:finish()

Finishes the request and returns the response body and the status code. Call this only when HTTPRequest:status returns "done". Does and returns nothing if the request is dead.

Methods

http.request

HTTPRequest http.request(string uri, [table post_params, [table headers]])

Constructs a HTTPRequest object and starts the underlying request immediately with the URI, post parameters and headers supplied. Both optional tables are collections of string key and string value pairs. The request is a POST if post parameters are supplied, a GET otherwise.