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
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.