Resource-Oriented
- REST is resource-oriented, not service-oriented. Resources are nouns, not verbs.
Addressable
- Every resource must be addressable by means of at least one URI (name). Names must be meaningful.
- Clients cannot access resources directly - they deal in representations of that resource (e.g, XML, JSON, ...)
- Resource representations would ideally be addressable (so that they can be passed around as URIs, eg. /rest/bookmarks.xml) The use of HTTP accept headers to specify representation is however acceptable, but should be provided as well as the addressable URI.
Stateless
- Resource state must not be confused with application (client state). Resource state should remain on the server, while application state should remain on the client.
Connected
- Resources should refer to other resources by means of their URIs.
Uniform Interface
- All interaction between clients and resources should be via the basic HTTP methods, preserving the semantics of those methods.
- GET: a request for information about a resource, delivered as a set of headers and a representation
- HEAD: like a GET, but only headers are required in response
- PUT: an assertion about the state of a resource, usually with a representation which the server will use to create or change the resource. PUT without any representation is an assertion that the resource should exist at that URI
- DELETE: an assertion that a resource should no longer exist, and should not include a representation
- POST: is an attempt to create a new resource from an existing one, the existing resource being a parent of the new one (in a data structure sense), or a factory resource whose purpose is to generate other resources. May also be used to append to the state of any existing resource.
- OPTIONS: rarely used, but is an attempt to discover which subset of the universe a resource supports.
- Consistent use of HTTP status codes (more on this in a future post)
Safety and Idempotence
- GET and HEAD requests must be safe, i.e. make no change to the server state, and should not have any material side effects.
- PUT and DELETE requests must be idempotent, i.e. repeatable
Multiple Representations
- The address of a resource can return several representations of the resource. The client tells the service which types of representations it can understand and the priority order in which it would like to receive them.
- All response content should be in JSON or XML according to HTTP Accept header, or failing that, request parameter format=xxxx. Default response format in the absence of a requested format should be JSON.