Skip to main content

Basic Internet-to-Agent Communications

Recommended Code Flow For Basic Agent HTTP Handling

The imp API provides agents with a standard methodology for handling incoming HTTP requests, typically from mobile apps or websites that wish to communicate with the device. Your agent code should deal with these requests by defining a request handler function and then registering that function to be called whenever the agent receives an HTTP request.

The handler function takes two parameters: a Squirrel table into which the decoded incoming HTTP request and its URL-encoded parameters have been placed, and an imp API httpresponse object which is instantiated for you to use to respond to the source of the request.

The request is a table containing the following keys:

Key Type Description
method string The HTTP method (verb), eg. "GET", "PUT", "POST"
path string The HTTP path, minus the agent ID
query table A table containing all of the query parameters (if any)
headers table A table containing all of the request headers
body string The request body, if any

The httpresponse object is used to acknowledge receipt of the request. This is done using the object’s member method httpresponse.send(). This takes two parameters: a standard HTTP Response Code as an integer, and a response message string to be set as the response’s body. If you need to add a header to the request, use the method httpresponse.header().

The response object can be stored as a global variable and used at a later time, typically after the device has been contacted and has returned data that needs to be relayed to the source of the request. The agent keeps the connection with the request source open until the response is sent.

Having defined your handler function, you must register it using the imp API method http.onrequest(). Only one handler may be registered at any one time; registering a second one will stop the first from being called. To prevent any handler from being called, pass null to http.onrequest().

If your agent takes too long to respond — it may be waiting for data from the device, say — the server will close the open connection automatically after ten minutes of inactivity. The sender of the HTTP request will receive the HTTP status code 504. If your agent has not implemented an HTTP request handler, the requester will receive a 404 error. For a list of the meanings of other HTTP error codes the requester may receive — and some suggested solutions — see HTTP Request Response Codes

Sample Code

The following code provides a minimal HTTP handler function with the recommended structure. The function is then registered as the callback for any incoming HTTP request. See the http.onrequest() documentation for a complete list of the fields passed into the handler’s first parameter. URL-encoded parameters and their values are passed to the handler as key-value pairs in a table.

With this core code, you will be able to quickly and conveniently expand your handler’s functionality to provide a complete URL-encoded API for your application.

API Properties Used

API Methods Used

Further Reading