REpresentational State Transfer is a software architectural style for creating stateless web APIs. These APIs are typically based on HTTP methods to access resources specified by URIs that are transmitted in JSON or XML encoded form. They are called RESTful APIs.

Resource oriented⌗

  • URI -> resource (and not action)
  • multiple URIs can point to the same resource (/employees/12, /departments/development/employees/2, …)
  • the resources are separate from the representation (same resource can be sent as JSON or XML for example)
  • manipulation through this representation
  • HATEOAS - resources can link to other resources, the client can discover the required content

HTTP based⌗

  • URL: the resource URI
  • HTTP methods: actions (GET/POST/PUT/DELETE)
  • HTTP response status: error handling (not found, bad request, not authorized…)
  • HTTP headers: cache-abilty, content negotiation, …

Stateless⌗

The server does not track the state of any client, the response is always based on only the request. Session state is typically handled by the client.

Example⌗

Retrive the user list:

GET /users

-> (200 OK) [{name: 'lili', id: 12}, {name: 'zsuzsi', id: 7}, ...]

Create new user:

POST /users
{name: 'gyuri'}

-> (201 Created) {name: 'gyuri', id: 16}

Modify user:

PUT /users/16
{name: 'dyuri'}

-> (200 OK) {name: 'dyuri', id: 16}

Delete user:

DELETE /users/16

-> (200 OK)

Tools⌗

  • browsers’ dev tools
  • browser extensions, like YARC
  • bigger tools like ARC
  • command line tools like httpie (oh, just noticed, that it has now desktop/webapp versions, too 🎉)

REST is not a standard, but an architectural style. Also, most APIs claiming to be RESTful does not implement HATEOAS - they just use resource URIs and HTTP methods, or even they definition of resource is not exact in some cases. I call these APIs REST-like, and they are completely fine in most cases - despite being non-stricly REST.