Boris Eetgerink

November 18, 2022

REST in 14 bullet points

Roy Fielding's dissertation on REST is very abstract. With these bullet points, I hope to make REST a bit more accessible and invite you to explore further.

  • REST is protocol independent, but is most often used over the HTTP protocol.
  • REST is not tied to a specific media type (JSON for example), but it does require a media type with hypermedia capabilities, for example HTML or the Ion Hypermedia Type.
  • JSON is not a requirement of a REST API.  
  • REST uses content negotiation to select the optimal media type for the client.
  • A REST client should understand hypermedia media type(s), it should not have prior knowledge of a specific server's implementation.
  • REST forbids (and doesn't require) an OpenAPI contract.
  • REST is stateless. All information required to satisfy a request is included in the request. There is no session state.
  • REST itself does not dictate which HTTP methods to use. That is determined by the HTTP protocol, when REST is used over HTTP.
  • REST is about workflows (or modeling actions, if you prefer), not about CRUD.
  • The response of a REST server to a request is a representation of a resource. That representation does not have to match the underlying storage (a database table for example).
  • Multiple URLs can point to the same resource and that's fine. For example: /posts/42/last-revision and /posts/42/revisions/3.
  • REST is about well-designed (user) interfaces that drive the state of the client application (hence Hypermedia as the engine of application state).
  • A REST server can 'program' a REST client through hypermedia controls without requiring changes to the client code.
  • All REST constraints together allow a server to evolve independently from the client, because there is no tight coupling.

Further reading

About Boris Eetgerink

Hey, thanks for reading my blog. Subscribe below for future posts like this one and check my personal site in order to contact me.