So you think you have RESTful API. But do you really? This topic comes back again and again in conversations. What is RESTful API and why follow RESTful guidelines?

First, let’s define what REST is, and what it is not. REST stands for REpresentational State Transfer, it is an architectural style developed by the W3C group, and can be used as a set of conventions and patterns for API architecture. REST is not a specification. There is no standards committee that provides protocol details or message structure. And REST is absolutely not defined by pretty URLs and JSON payloads.

Roy Fielding (1), defines REST using six constraints:

  • Client-Server – separation of concerns allows for variations of layers.
  • Stateless – no sessions, no cookies to maximize scalability.
  • Cacheable – responses must be explicitly marked as cacheable to improve scalability and minimize client-server interactions.
  • Layered System – don’t count on client talking to a server directly, the web adds silent invisible dependencies.
  • Code on demand – not only resources but the code to execute, like JavaScript. This is optional.
  • Uniform Interfaces – uniformity between client and server for the identification of resources.

As long as your app complies with the above constraints you can consider it RESTful. In practice, more concrete constraints are added based on industry practices. We have to drill down deeper into technology layer and match these constraints to particular technologies. From all this good theoretical stuff several concrete recommendations materialized based on current web technologies and practices:

  1. Use JSON for message content. It is ubiquitous, JavaScript everywhere can understand it. It is simple – strings and object maps, and it is human readable.
  2. URLs for resources identifications. They are widely accepted as resource identifiers on the web. Some guidelines: use nouns, keep them coarse-grained, stick to your use cases, separate collections and instances.
  3. Use HTTP verbs. GET – query, POST – create, PUT – full update, DELETE – self-explanatory, PATCH – partial update.
  4. Media types are important, the accept header tells the server what format client understands, the server sends Content-Type to tell the client what’s being sent back.
  5. Versioning: use URLs, /v1/. Media types also support versioning by appending “;application&v=1” to the media type header.

There are of course more best practices surrounding authentication, encryption, and other concerns, but they are not strictly REST-related, but more of general practices.

In conclusion, follow REST constraints and industry best practices, because that’s what other developers, who will be consumers of your API, expect.

REFERENCES
(1) http://www.ics.uci.edu/~taylor/documents/2002-REST-TOIT.pdf