REST: REST Concepts and Practices Summary

Posted on By Andre Dias
network, protocol, web design

An Ordered Information Collection from Several Sources

IMPORTANT NOTE

This post is a summary of my researches.
The texts are copied as they are or adapted to make it shorter or to make it fit the summary’s purpose.
They are all referenced, sometimes twice — in loco or below under References topic.

There is no intention of plagiarism.
The intention here is to share my research putting together important concepts, grouped and ordered from several resources.

If some content here displeasures an author, please contact me that I’ll be glad to remove it, including its reference.

Thank you for all those authors that spent their time and effort to share information.

 

 

#REST

First of all, REST does not define a standard message exchange format.
You can build REST services with both XML and JSON.
However, JSON is a more popular format with REST.

So, if it does not define a standard message exchange format, what is REST then?
REST is a style of software architecture for distributed hypermedia systems.
REST stands for REpresentational State Transfer.
The definitions for REST can be vague.

Key abstraction in REST is a Resource.
There is no restriction on what can be a resource.
A todo is a resource.
A person on Facebook is a resource.

#RESOURCE

The key abstraction of information in REST is a resource.

Any information that can be named can be a resource: a document or image, a temporal service (e.g. “today’s weather in Los Angeles”), a collection of other resources, a non-virtual object (e.g., a person), and so on.

In other words, any concept that might be the target of an author’s hypertext reference must fit within the definition of a resource.

A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.

Roy Fielding’s dissertation

#Resource archetypes

Four categories: document, collection, store and controller.

#document

A document resource is a singular concept that is akin to an object instance or database record. In REST, you can view it as a single resource inside resource collection. A document’s state representation typically includes both fields with values and links to other related resources.

Use “singular” name to denote document resource archetype.

http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin
#collection

A collection resource is a server-managed directory of resources. Clients may propose new resources to be added to a collection. However, it is up to the collection to choose to create a new resource or not. A collection resource chooses what it wants to contain and also decides the URIs of each contained resource.

Use the “plural” name to denote the collection resource archetype.

http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts
#store

A store is a client-managed resource repository. A store resource lets an API client put resources in, get them back out, and decide when to delete them. A store never generates new URIs. Instead, each stored resource has a URI. The URI was chosen by a client when it was initially put into the store.

Use “plural” name to denote store resource archetype.

http://api.example.com/song-management/users/{id}/playlists
#controller

A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs.

Use “verb” to denote the controller archetype.

http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play

@SEE:
REST Resource Naming Guide

 

#Resource Naming – Key Consistency Practices

Basic Rules:

  • REST APIs use Uniform Resource Identifiers (URIs) to address resources.
  • A resource shall be mapped to a noun, except for controller resource models as procedure concept that use verbs.
    Note: verbs are used by the HTTP protocol.
  • The nouns use their plural forms, except for document.
  • It is not used underscore ( _ ).
  • Do not use trailing forward-slash (/) in URIs.
  • Use hyphens (-) to improve the readability of URIs.
  • URIs use just lowercase.
  • URIs do not carry file extensions.
  • URIs do not use CRUD function names.
    Instead use HTTP verbs to indicate.
    Example: 
    HTTP GET http://api.example.com/device-management/managed-devices  //Get all devices
  • Use query component to filter URI collection.
    Many times, you will come across requirements where you will need a collection of resources sorted, filtered or limited based on some certain resource attribute. For this, do not create new APIs – rather enable sorting, filtering and pagination capabilities in resource collection API and pass the input parameters as query parameters. e.g.</ 
    http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date
  • A resource may represent a Singleton, a Collection and a Sub-collection

A resource can be a singleton or a collection.
For example, “customers” is a collection resource and “customer” is a singleton resource (in a banking domain). We can identify “customers” collection resource using the URI “/customers”. We can identify a single “customer” resource using the URI “/customers/{customerId}”.

A resource may contain sub-collection resources also.
For example, sub-collection resource “accounts” of a particular “customer” can be identified using the URN “/customers/{customerId}/accounts” (in a banking domain). Similarly, a singleton resource “account” inside the sub-collection resource “accounts” can be identified as follows: “/customers/{customerId}/accounts/{accountId}”.

@FROM:
REST Resource Naming Guide

#FORMATS

XML
HTML
JSON
A resource will have state. The representation of a resource should capture its current state.
When a resource is requested, we provide the representation of the resource.

#PROTOCOL

REST and HTTP
REST builds on top of HTTP (Hypertext Transfer Protocol).

#VERBS

HTTP has a few important verbs.

POST – Create a new resource
GET – Read a resource
PUT – Update an existing resource
DELETE – Delete a resource
HTTP also defines standard response codes.

#other verbs

#PATCH

PUT vs. PATCH Baeldung

#SUCCESS CODE

200 – SUCESS
404 – RESOURCE NOT FOUND
400 – BAD REQUEST
201 – CREATED
401 – UNAUTHORIZED
415 – UNSUPPORTED TYPE – Representation not supported for the resource
500 – SERVER ERROR

#SPRING BOOT

Creating a CRUD REST API/Service with Spring Boot, JPA and Hibernate
Spring Boot Rest API Example

 

#REFERENCES

The references here are also used as sources since their texts may be inserted in this post as they are.
There is no intention to change words to masquerade the authors’ privileges.
Sources’ references emphasized in loco may also be referenced here or not.

REST Resource Naming Guide

Best Practices for Designing a Pragmatic RESTful API

Creating a CRUD REST API/Service with Spring Boot, JPA and Hibernate
Spring Boot Rest API Example

PUT vs. PATCH Baeldung