REST

Today, REST (REpresentational State Transfer) is arguably the most discussed API architecture style, and certainly one of the most used.

REST can be defined as a stateless, layered and cacheable client-server architecture that operates with resources using a uniform command interface based on HTTP verbs. A resource is an entity (such as a document or file) that can be addressed with a unique resource locator (URL).

The strongest REST convention is to use a URL to express the resource you're working with, and a HTTP verb to express the action to take.

REST aims to follow HTTP semantics closely: a REST request is structured like an HTTP request. REST uses HTTP verbs - GET, POST, PUT, DELETE and PATCH - to reflect the intention of the action being taken:

1GET /employees/25

1PUT /employees/25
2{
3"position": "Regional Director"
4}

1DELETE /departments/3

Requests that the REST client sends to the server are stateless: every request occurs in complete isolation. When the client makes a request, it includes all information necessary for the server to process that request. The server never stores information from previous requests: if that information is critical, it's the client's responsibility to resend it with each subsequent request.

REST requires requests to be cacheable when possible, and caching is implemented using HTTP's native caching headers. This doesn't apply to all HTTP verbs though: while GET requests should be cacheable by default, POST requests can be made cacheable using headers, while POST and DELETE are not cacheable at all.

A REST API should be idempotent where possible - that is, making multiple identical requests should have the same effect as making a single request. This helps keep the API stable even when request duplication occurs due to network errors.

Compared to RPC, REST is loosely coupled: the server only has to expose resources that are being asked for, and there's a relatively small, well defined set of actions that can be done on those resources. The client only needs to know about the resources that the server exposes.

Since REST is designed to work with resources, it is a great fit when a domain can be easily described as a set of resources (as opposed to actions). When a domain is described this way, using standard HTTP methods in REST enables basic CRUD operations (create, read, update, delete) on all the domain's data.

REST is great for public-facing interfaces: because it's directly built upon the semantics of HTTP, it's intuitive for the consumer. On a related note, it's generally easier to keep REST APIs consistent and clean than it is with RPC style APIs.

REST has its own issues though:

• It's not a great fit for doing things that can't be directly mapped to resources. If you want to send an email, it's hard to do in a RESTful way as there's no resource to act upon (unless you have an "email" resource).
• If you have nested entities (for example, you want to get users along with their comments), you'll need to make multiple roundtrips to build up your state.