API Design: Ruminating Over REST
Over the next several blog posts, we’d like to discover what hypermedia as the engine of application state, or HATEOAS (“Hay-dee-us”), means. We'll start by considering each of the six constraints of the architectural style of REST as defined by Roy Fielding in his PhD dissertation, with an emphasis on HATEOAS.
The Constraints of REST
- Stateless server
- Uniform interface
a. Identification of resources
b. Manipulation of resources through representations
c. Self-descriptive messages
d. Hypermedia as the engine of application state or HATEOAS
- Layered system
- Code-on-demand (optional)
The first three constraints—client-server, stateless server, and cache—combine to give us the robust client-cache-stateless-server architecture that allows today’s Web to scale. Requests travel to and exchange information with the server. The server does not store data from client requests, but the client can reuse response data, sent by the server, by storing it in a local cache.
Let’s move on to the layered systems constraint; we’ll save the uniform interface constraint for a later discussion.
The layered systems constraint lets us add features like a gateway, a load balancer, or a firewall to accommodate system scaling. Layers can encapsulate legacy services and protect new services from legacy clients. Each layer is also limited to communication with its immediate neighbors. The trade off is reduced performance from increased levels of indirection associated with multiple layers.
Resource identifiers interact between components. On today’s Web, they are expressed as:
GET /#!/jack/status/20 HTTP/1.1 User-Agent: Chrome/18.0.1025.11 Host: twitter.com Accept: text/html
Self-descriptive messages contain metadata to describe the meaning of the message. The methods used to invoke the message must be standard and agreeable between the first three constraints - client-server, stateless server, and cache.
To join the conversation around APIs, check out the API Craft Google Group and the IRC Channel #api-craft on freenode.
For further reading, see:
A special thanks to the api-craft Google group, who helped pull this content together.
Next: API Design: Honing in on HATEOAS