DEV Community

Discussion on: What is RESTFUL API ?

peerreynders profile image

In 2007 RESTful Web Services was published and described REST as (p.105) (or resource oriented archtiecture (ROA); ROCA);

It's just four concepts:

  • Resources
  • Their names (URIs)
  • Their representations
  • The links between them

and four properties

  • Addressability
  • Statelessness
  • Connectedness
  • A uniform interface


  • Resources (p.81): If it's important enough to be referenced "by itself" then it should be a resource with its own unique name/identity.
  • Addressability (p.84): Resources have to be referenced somehow. In the case of the Web the resource's URI (p.81) becomes its URL.
  • Representations (p.91): Often the actual "resource" cannot be manipulated directly. So instead the resource is manipulated through one of it's "Representations". The resource representation can be simultaneously published in multiple formats like XHTML, XML, JSON or any other IANA MIME media type. However strong preference is given to media types that support another REST property - connectedness; the representation format should allow for standardized links to other resources. In the case of the Web you want to the format to expose URIs in a standard way (e.g. HTML's anchor element). To change a resource's state you retrieve the representation, modify it, and write it back.
  • Statelessness (p.86): No server-side application (client) state. The only state that exists on the server is resource state (which is captured in its representation). Application state stays on the client.
  • Links and Connectedness (p.94) of resources (hypermedia as the engine of application state - HATEOAS): Any resource can and should link (in it's representation) to other resources (via the URIs). A RESTful application tends to have one single root resource where each "session" starts. The possible client application state transitions are described as links to other resources inside each resource's representation. So the navigation from one resource to the next is what is changing (and defining) application/client state.
  • Uniform Interface (p.97) exposed by resources: Every resource implements the same Uniform Interface (or at least a significant subset). In the case of the Web, the Uniform interface is defined through the HTTP methods (GET ,PUT, DELETE etc.) - one should stick with the safe and idempotent methods whenever possible.

In some ways the article is focusing more on contemporary implementation patterns, practices and technologies used by general APIs-over-HTTP that may claim to be RESTful. Sometimes that claim comes from tooling that tries to position itself in the "RESTful" space - e.g. Swagger ain't REST - is that OK?. Quite often APIs are just a collection of documented URI templates with JSON responses while completely lacking the hypermedia aspect (links and connectedness) inside the representation.

This isn't about some standard of absolute purity but the fact the term RESTful doesn't really communicate anything useful these days. The idea behind REST is an architecture that's aligned with the nature of the web of interconnected resources rather than just tunnelling RPC as JSON payloads over HTTP. REST is data-oriented so it isn't suitable for all API styles (resource design for transactions).

REST and Hypermedia in 2019