nodemcu-firmware/docs/modules/http.md

HTTP Module

Since	Origin / Contributor	Maintainer	Source
2018-10-27	Tom Sutcliffe	Tom Sutcliffe	http.c

HTTP client module that provides an interface to do GET/POST/PUT/DELETE over HTTP and HTTPS, as well as customized requests. It can support large requests with an API similar to that of the net module. Multiple concurrent HTTP requests are supported. Both synchronous and asynchronous modes are supported.

For each operation it is possible to provide custom HTTP headers or override standard headers. By default the Host header is deduced from the URL and User-Agent is NodeMCU (ESP32). Requests are always sent as HTTP/1.1. Keep-alive is supported (unless using the one-shot APIs) by default, disable by adding a Connection: close header or by explicitly closing the connection once complete.

HTTP redirects (HTTP status 300-308) are followed automatically up to a limit of 10 to avoid redirect loops. This behavior may be customized by setting the max_redirects option.

Whenever headers are returned or passed into a callback, the header names are always lower cased. If there are multiple headers of the same name, then only the last one is returned.

http.createConnection()

Creates a connection object which can be configured and then executed. Note this function does not actually open the connection to the remote server, that doesn't happen until connection:request() is called.

Syntax

http.createConnection(url, [method,] [options])

Parameters

• url The URL to fetch, including the http:// or https:// prefix. Required.
• method The HTTP method to use, one of http.GET, http.POST, http.PUT, http.DELETE or http.HEAD. Optional and may be omitted, the default is http.GET.
• options An optional table containing any or all of:
  • async If true, the request is processed asynchronously, meaning request() returns immediately rather than blocking until the connection is complete and all callbacks have been made. Some other connection APIs behave differently in asynchronous mode, see their documentation for details. If not specified, the default is false, meaning requests are processed synchronously.
  • bufsz The size in bytes of the temporary buffer used for reading data. If not specified, the default is 512.
  • cert A PEM-encoded certificate (or certificates). If specified, the server's TLS certificate must chain back to one of these root or intermediate certificates otherwise the request will fail. This option is ignored for HTTP requests (unless they redirect to an HTTPS URL).
  • headers Table of headers to add to the request.
  • max_redirects Maximum number of 30x redirects to follow before giving up. If not specified, the default is 10. Specify 0 to disable following redirects entirely.
  • timeout Network timeout, in milliseconds. If not specified, the default is 10000 (10 seconds).

Returns

connection The connection object.

Example

headers = {
  Connection = "close",
  ["If-Modified-Since"] = "Sat, 27 Oct 2018 00:00:00 GMT",
}
connection = http.createConnection("http://httpbin.org/", http.GET, { headers=headers } )
connection:on("complete", function(status)
  print("Request completed with status code =", status)
end)
connection:request()

HTTP connection objects

connection:on()

Set a callback to be called when a certain event occurs.

Syntax

connection:on(event[, callback])

Parameters

• event One of
  • "connect" Called when the connection is first established. Callback receives no arguments.
  • "headers" Called once the HTTP headers from the remote end have been received. Callback is called as callback(status_code, headers_table).
  • "data" Can be called multiple times, each time more (non-headers) data is received. Callback is called as callback(status_code, data).
  • "complete" Called once all data has been received. Callback is called as callback(status_code, connected) where connected is true if the connection is still open.
• callback a function to be called when the given event occurs. Can be nil to remove a previously configured callback.

If an error occurs, the status_code in the callback will be a negative number. The only callback guaranteed to be called in an error situation is complete.

If the connection is asynchronous, the data callback may optionally return the constant http.DELAYACK to indicate that no further callbacks should be made until connection:ack() is called. This is useful to slow down the arrival of data in cases where the system is not ready to receive any more. If desired, non-delayed acks may be indicated by returning http.ACKNOW but this is not required since it's the default behaviour anyway.

Note, you must not attempt to reuse connection until the complete callback has been called, or (in synchronous mode) until request() returns. You may reuse the connection from within the complete callback (in either mode). You may call connection:close() from within any callback to indicate that the connection should be aborted; in any callback other than complete, this will result in a subsequent complete callback.

Returns

nil

Example

See http.createConnection().

connection:request()

Opens the connection to the server and issues the request. If async was set to true in the connection options, then this function returns immediately. Otherwise, the function doesn't return until all callbacks have been made and the request is complete. If the server supports Keep-Alive and Connection = "close" wasn't specified in the headers, the connection will remain open after completion, ready for another call to request() (possibly after setting a new URL with connection:seturl()).

Syntax

connection:request()

Parameters

None

Returns

In asynchronous mode, always returns nil.

In synchronous mode, it returns 2 results, status_code, connected where connected is true if the connection is still open. In that case, if you don't wish to use the socket again, you should call connection:close() to ensure the socket is not kept open unnecessarily. When a connection is garbage collected any remaining sockets will be closed.

connection:setmethod()

Sets the connection method. Useful if making multiple requests of different types on a single connection. Errors if called while a request is in progress.

Syntax

connection:setmethod(method)

Parameters

• method one of http.GET, http.POST, http.PUT, http.HEAD, http.DELETE.

Returns

nil

Example

connection:setmethod(http.POST)

connection:seturl()

Sets the connection URL. Useful if making multiple requests on a single connection. Errors if called while a request is in progress.

Syntax

connection:seturl(url)

Parameters

• url Required. The URL to use for the next request() call.

Returns

nil

Example

connection = http.createConnection("http://httpbin.org/")
connection:request()
-- Make another request
connection:seturl("http://httpbin.org/ip")
connection:request()

connection:setheader()

Sets an individual header in the request. Header names are case-insensitive, but it is recommended to match the case of any headers automatically added by the underlying library (for example: Connection, Content-Type, User-Agent etc). Errors if called while a request is in progress.

Syntax

connection:setheader(name[, value])

Parameters

• name name of the header to set.
• value what to set it to. Must be a string, or nil to unset it.

connection:setbody()

Sets the body data to be used for this request (for POST, PUT, etc). If a Content-Type header has not already been set, also sets that to application/x-www-form-urlencoded. Errors if called while a request is in progress.

Syntax

connection:setbody([data])

Parameters

data The data to POST/PUT/etc.. Unless a custom Content-Type header has been set, this data should be in application/x-www-form-urlencoded format. Can be nil to unset what to post and the Content-Type header.

Returns

nil

connection:ack()

Completes a callback that was previously delayed by returning http.DELAYACK. This unblocks the request and allows subsequent callbacks to occur. Errors if the most recent callback wasn't an asynchronous one that was delayed.

Syntax

connection:ack()

Parameters

None

Returns

nil

connection:close()

Closes the connection if it is still open. Note this does not reset any configured URL or callbacks on the connection object, it just closes the underlying TCP/IP socket. If called from within a callback, this aborts the connection, but the connection object must not be reused until the complete callback occurs (waiting until after request() returns is also allowed, if the request was synchronous). In the case of a connection in asynchronous mode, will error if called from outside of a callback while a request is ongoing, unless the last callback returned http.DELAYACK and connection:ack() has not yet been called. In such a situation, connection:ack() must still be called, after the call to connection:close(). An asynchronous connection that is still open but not ongoing (ie the complete callback has taken place) may be closed without restriction.

Syntax

connection:close()

Parameters

None

Returns

nil

One shot HTTP APIs

These APIs are wrappers around the connection object based APIs above. They allow simpler code to be written for one-off requests where complex connection object management is not required. Note however that they buffer the incoming data and therefore are limited by free memory in how large a request they can handle. The EGC can also artificially limit this - try setting node.egc.setmode(node.egc.ON_ALLOC_FAILURE) for more optimal memory management behavior. If however there is physically not enough RAM to buffer the entire request, then the connection object based APIs must be used instead so each individual data callback can be processed separately.

All one-shot APIs add the header Connection: close regardless of what the options.headers parameter contains, and can be executed either synchronously or asynchronously, depending on whether a callback is specified, regardless of any options.async setting.

• Synchronous mode: The call to get()/post() does not return until the request is complete, and the results of the request are returned from the call.
• Asynchronous mode: The call returns immediately (with no results), the results of the request are given as arguments to the callback function.

If more advanced control over the request is required, the connection object based APIs http.createConnection() and connection:request() should be used instead.

http.get()

Make an HTTP GET request. If a callback is specifed then the function operates in asynchronous mode, otherwise it is synchronous.

Syntax

http.get(url, [options,] [callback])

Parameters

• url The URL to fetch, including the http:// or https:// prefix
• options Same options as http.createConnection(), except that async is set for you based on whether a callback is specified or not. May be nil or omitted.
• callback Should be nil or omitted to specify synchronous behaviour, otherwise a callback function to be invoked when the response has been received or an error occurred, which is called with the arguments status_code, body and headers. In case of an error status_code will be a negative number.

Returns

In synchronous mode, returns 3 results status_code, body, headers once the request has completed. In asynchronous mode, returns nil immediately.

Example

-- Asynchronous mode
http.get("http://httpbin.org/ip", function(code, data)
    if (code < 0) then
      print("HTTP request failed")
    else
      print(code, data)
    end
  end)
  
-- Synchronous mode
code, data = http.get("http://httpbin.org/ip")
if (code < 0) then
    print("HTTP request failed")
else
    print(code, data)
end

http.post()

Executes a single HTTP POST request and closes the connection. If a callback is specifed then the function operates in asynchronous mode, otherwise it is synchronous.

Syntax

http.post(url, options, body[, callback])

Parameters

• url The URL to fetch, including the http:// or https:// prefix
• options Same options as http.createConnection(), except that async is set for you based on whether a callback is specified or not. May be nil.
• body The body to post. Required and must already be encoded in the appropriate format, but may be empty. See connection:setbody() for more information.
• callback Should be nil or omitted to specify synchronous mode, otherwise a callback function to be invoked when the response has been received or an error occurred, which is called with the arguments status_code, body and headers. In case of an error status_code will be a negative number.

Returns

In synchronous mode, returns 3 results status_code, body, headers once the request has completed. In asynchronous mode, returns nil immediately.

Example

headers = {
  ["Content-Type"] = "application/json",
}
body = '{"hello":"world"}'
http.post("http://httpbin.org/post", { headers = headers }, body,
  function(code, data)
    if (code < 0) then
      print("HTTP request failed")
    else
      print(code, data)
    end
  end)

http.put()

Executes a single HTTP PUT request and closes the connection. If a callback is specifed then the function operates in asynchronous mode, otherwise it is synchronous.

Syntax

http.put(url, options, body[, callback])

Parameters

• url The URL to fetch, including the http:// or https:// prefix
• options Same options as http.createConnection(), except that async is set for you based on whether a callback is specified or not. May be nil.
• body The body to post. Required and must already be encoded in the appropriate format, but may be empty. See connection:setbody() for more information.
• callback Should be nil or omitted to specify synchronous mode, otherwise a callback function to be invoked when the response has been received or an error occurred, which is called with the arguments status_code, body and headers. In case of an error status_code will be a negative number.

Returns

In synchronous mode, returns 3 results status_code, body, headers once the request has completed. In asynchronous mode, returns nil immediately.