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, this is my C# .NET blog. I don't have a comments system, but you can contact me at boriseetgerink at hey dot com.