REST Logo

The principle is to break down the application into resources that clients can use through HTTP requests.

This architecture for distributed systems was created in 2000 by Roy Fielding in his doctoral thesis.

The benefit of a REST API is making the application’s resources usable by all its components. This enables implementing microservices, portability, and giving external parties access to certain features.

Resource Identification by URL

Each resource must be identified via a URL that is logically structured. Resource names should use the plural form to indicate that without filtering parameters, all elements are displayed. When filtering, we keep the plural, implying that we retrieve all elements then return only the filtered one.

For example:

  • http://example.com/books Retrieves the list of all books.
  • http://example.com/books/5 Retrieves the book list then filters to get the one with ID 5.

We can then retrieve associated resources using the same method:

  • http://example.com/books/5/comments Retrieves book 5’s associated comments.
  • http://example.com/books/5/comments/6 Retrieves comment 6 of book 5.

Using HTTP Verbs to Identify Operations

The available HTTP verbs for identifying actions on a resource are:

  • GET: Requests a representation of the specified resources.
  • HEAD: Same as GET but only returns the response header.
  • POST: Used to create a resource.
  • PUT: Used to update a resource.
  • DELETE: Used to delete a resource.
  • CONNECT: Establishes a tunnel to the server identified by the target resource.
  • OPTIONS: Describes the communication options for the target resource.
  • TRACE: Performs a round-trip following the path of the target resource.
  • PATCH: Used to apply partial modifications to a resource.

For example, to create a CRUD for books:

  • Create: POST http://example.com/books
  • Read: GET http://example.com/books/4
  • Update: PUT http://example.com/books/4
  • Delete: DELETE http://example.com/books/4

The Response Represents the Resource

The response must be easily understandable. The process that makes this possible is object serialization and deserialization. Contents can be objects, arrays, and simpler variables such as booleans, numbers, strings, or null values.

The most common data formats are:

  • JSON (JavaScript Object Notation)
  • XML (Extensive Markup Language)
  • YAML (Yet Another Markup Language)
  • CSV (Comma-Separated Values)
  • INI

Example of an object represented in JSON:

{
    "name":"John",
    "age":30,
    "car":"Fiat"
}

Authentication for Accessing a Resource

Restricting access to certain resources is essential in a REST API architecture. One challenge is that this type of architecture must be based on stateless servers, meaning sessions should not be stored on servers to allow the service to scale easily.

  • Session token stored in a shared database
  • API Key
  • JWT
  • OAuth 2

Using URL Parameters for Greater Data Control

URL parameters can be useful for performing additional processing on data, most commonly used with HTTP GET requests. For example, we can add a “sort” parameter for ORDER BY on results. We can also add a pagination system to fragment results if the resource is too large.

  • http://example.com/books?filter=detective&sort=asc

  • http://example.com/books?filter=detective&sort=asc&page=4&elementsPerPage=25

Further Reading

Translation of Chapter 5 of Roy Fielding’s thesis: