RESTful Web APIs

Key points:

• Client / Server: The Clients aren't generally storing databases, doing huge calculations, or sharing data between clients, the servers aren't tasked with user interface or keeping track of client information (other than authentication).
• Stateless: We don't require the server to remember anything about the client. e.g. no client specific Application data stored on the server. The client must send all the data required to identify it's needs with each request. This makes authentication a bit tricky as it must be done for each request.
• Uniform: The interface between the client and server is well documented and doesn't change.
  • The base URI should provide a list of hyperlinked action URI's exposed by the server. E.g. In a web service managing IOT devices, one link might provide a list of devices, another link provides data given the ID of one device, another a way to add a new device or removing an existing one.
  • Any needed resource is referenced in the request, usually by URI. The resource is not the representation. E.g. access to a database on the server might be via http://api.mydomain.com/devices and the data returned might be a list of known devices in XML, JSON, or even plain text.
  • The data returned must provide enough information for the client to be able to act on that resource. For example, the ID of the device should be included in the device list returned, so that the client can request additional data about that device. Or request the device be removed. The data format should be specified in the media type.
  • The representation of the data must include descriptions. E.g. XML typically is self describing. A pure text response would not be appropriate without some sort of header, unless it was a single column list. JSON is also an excellent example of self describing data.

Standard HTTP methods (GET, PUT, POST, DELETE) are used.

• GET never changing anything, it just requests data.
• PUT and DELETE return no information (other than status) about the data, they only take action. Also, they should not be incremental; they should do the same single operation no matter how many times they are called. E.g. there is no "delete next 1 record" command, there is only a "delete record number #" command. You can't PUT a request to add a new item without a unique ID. You can GET a unique id for a new item, then PUT that item to the database.

Requests can be cashed and repeated. If "fresh" data is required, some means of making a new request should be included. E.g. if you need to know if the database has changed within some specific time, include the time in the request.