REST API

I recently read a new book RESTful Web APIs by Leonard Richardson and Mike Amundsen. A key notes about REST API I presented in this post.

REST

Representational State Transfer (REST) is not a protocol, a file format, or a development framework. REST is an architectural style. Another definition says that REST is a set of design constraints. REST was initially described in the context of HTTP, but it is not limited to that protocol. RESTful architectures may be based on other Application Layer protocols if they already provide a rich and uniform vocabulary for applications based on the transfer of meaningful representational state.

The REST architectural style describes the following six constraints applied to the architecture:

Client–server

Servers are not concerned with the user interface or user state, so that servers can be simpler and more scalable. Servers and clients may also be replaced and developed independently, as long as the interface between them is not altered.

Stateless

Each request from any client contains all of the information necessary to service the request, and session state is held in the client.

Cacheable

As on the World Wide Web, clients can cache responses. Well-managed caching partially or completely eliminates some client–server interactions, further improving scalability and performance.

Layered system

A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way. Intermediary servers may improve system scalability by enabling load-balancing and by providing shared caches. They may also enforce security policies.

Uniform interface

The uniform interface between clients and servers, simplifies and decouples the architecture, which enables each part to evolve independently.

Code on demand - optional

Servers can temporarily extend or customize the functionality of a client by the transfer of executable code. Examples of this may include compiled components such as Java applets and client-side scripts such as JavaScript.

Resources and representation

Individual resources are identified in requests, for example using URIs in web-based REST systems. The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server does not send its database, but rather, some HTML, XML or JSON that represents some database records.

Although a resource can be anything at all, a client can’t do whatever it wants to a resource. There are rules. In a RESTful system, clients and servers interact only by sending each other messages that follow a predefined protocol.

The HTTP standard defines eight different kinds of messages.

GET

The client sends a GET request to ask for a representation of a resource, identified by a URL. The GET is defined as a safe HTTP method.  It’s just a request for information.

The most common response code to a GET request is 200 (OK). Redirect codes like 301 (Moved Permanently) are also common.

DELETE

The client sends a DELETE request when it wants a resource to go away. If a DELETE request succeeds, the possible status codes are 204 (No Content), 200 (OK); and 202 (Accepted).

If a client tries to GET a resource that has been DELETEd, the server will return an error response code, usually 404 (Not Found) or 410 (Gone).

DELETE is not a safe method. Once you delete a resource, it’s gone. The resource state has permanently changed. You can send another DELETE request, and you might get a 404 error, but the resource state is exactly as it was after the first request. The resource is still gone. That’s idempotence.

POST

Sending a POST request to a resource creates a new resource. When a client sends a POST request, it sends a representation of the resource it wants to create in the request’s entity-body. The most common response code to a POST request is 201 (Created). The Location header lets the client know the URL to this new resource. Another common response code is 202 (Accepted), which means that the server intends to create a new resource based on the given representation, but hasn’t actually created it yet.

The POST method is neither safe nor idempotent. Every POST create a new resource.

PUT

A PUT request is a request to modify resource state. The client takes the representation it got from a GET request, modifies it, and sends it back as the payload of a PUT request. If the server decides to accept a PUT request, the server changes the resource state to match what the client says in the representation, and usually sends either 200 (OK) or 204 (No Content).

PUT is idempotent, just like DELETE. If you send the same PUT request 10 times, the result is the same as if you’d only sent it once.

HEAD

HEAD is a safe method, just like GET. The server is supposed to treat a HEAD request exactly the same as a GET request, but it’s not supposed to send a an entity-body—only the HTTP status code and the headers.

Using HEAD instead of GET may not save any time (the server still has to generate all the appropriate HTTP headers), but it will definitely save bandwidth.

OPTIONS

OPTIONS is a primitive discovery mechanism for HTTP. The response to an OPTIONS request contains the HTTP Allow header, which lays out which HTTP methods the resource supports.

200 OK

Allow: GET PUT DELETE HEAD OPTIONS

PATCH

Representations can get really big. “Modify the representation and PUT it back” is a simple rule, but if you just want to change one little bit of resource state, it can be pretty wasteful. The PUT rule can also lead to unintentional conflicts with other users who are modifying the same document. It would be nice if you could just send the server the parts of the document you want to change.

The PATCH method allows for this. Instead of PUTting a full representation, you can create a special “diff ” representation and send it to the server as the payload of a PATCH request.

The best response codes for a successful PATCH are the same as for PUT and DELETE: 200 (OK) if the server wants to send data (such as an updated representation of the resource) along with its response, and 204 (No Content) if the server just wants to indicate success.

PATCH is neither safe nor idempotent.

Remember that PATCH is not defined in the HTTP specification. It’s an extension designed specifically for web APIs, and it’s relatively recent (RFC 5789 was published in 2010). This means that tool support for PATCH, and for the diff

documents it uses, is not as good as the support for PUT.

LINK and UNLINK

LINK and UNLINK manage the hypermedia links between resources. These methods are defined in an Internet-Draft, and until that draft is approved as an RFC, tool support for them will be even worse than for PATCH.

LINK and UNLINK are idempotent, but not safe.