Web Services for Smart Objects - Part 3: A real-world web service system for smart objects

GET: This request method is used to retrieve sensor data from a Pachube server. With a GET request, the URI provided as part of the request contains both the identity of the data feed and the client's data format. The URI contains information about the type of data the client wants to receive, the identity of the feed, and what data format the client wants. The identity of the data feed is given as the directory part of the HTTP URI, whereas the data format is provided as a fi le extension.

PUT: This method is used when submitting new sensor data to the Pachube server. Data to be submitted from the client to the server are provided in the data portion of the HTTP request, which follows the HTTP header. As with the GET request, the feed identity and the data format are included in the HTTP URI that is sent together with the HTTP request.

POST: This request method is used to create a feed and to create a new data stream within a previously established feed. The body of the HTTP request sent by the client contains the defi nition of the feed or the data stream. The definition is provided in EEML format. When establishing a stream, the server creates a stream into which the client may use the PUT method to insert data.

DELETE: This request method is used to delete a data feed or a data stream. The URI provided with the request contains the identifier of the feed or stream. Once a feed or stream has been deleted, it cannot be restored.

9.3.4 HTTP Return Codes
On every HTTP request the server responds to the client with a return code. The return code provides information about the request, such as if the request was successful or erroneous. If there was an error, the return code contains information about the cause of the error. HTTP return codes are represented as three-digit numbers. The basic HTTP return codes are specified in the base HTTP specifi cation [83], but many HTTP servers have added their own codes.

The Pachube API uses HTTP return codes to inform the client about the state of the request. The return codes are sent to successful transactions as well as failed ones. For failed transactions, the return code provides insight into what caused the problem, and the HTTP body contains an XML document containing an error message.

The HTTP return codes used by the Pachube API are

• 200 OK: This code is returned when a request is completed successfully. Unlike the other return codes, this one does not indicate an error.
• 401 Not Authorized: This return code is sent in response to a client request that needed authentication, but where the authentication key was invalid or not present.
• 403 Forbidden: This error code is returned when the Pachube servers did not execute the request. The reason the server did not respond to the request is given in the body of the HTTP reply.
• 404 Not Found: The requested URI was not found. Either the feed it requested could not be found, or the method that the client invoked did not exist.
• 422 Unprocessable Entity: This return code is sent in response to client requests that contain EEML data. The return code tells the client that the EEML contained semantic errors, even if it was syntactically correct.
• 500 Internal Server Error: This return code is sent when there is an internal error with the Pachube servers.
• 503 No Server Error: This return code is sent when there are no Pachube servers available to complete a request.