REST APIs demystified

Working as a web developer, the day necessarily came when you faced the need to exchange data between browser and server, and heard about REST(ful) APIs.

REST stands for Representational state transfer and is a data-exchange architectural style strongly based on HTTP protocol.

It was originated in 2000 by Roy Fielding (co-author of HTTP specification and co-founder of Apache HTTP server) in a dissertation, which is still considered as of today like a major contribution to Web standards.

It's worth mentioning that REST is a collection of principles not published by any means as a standard or specification. This fact is probably the top reason why junior developers often struggle to efficiently grasps its concepts.

A RESTful API — or more commonly a REST API — is an API trying to follow REST principles as much as possible.

• Philosophy / Concepts
• Key principles
  • Resource-identifiers URIs
  • HTTP methods
  • Single-resource endpoints
  • HTTP status codes

Philosophy / Concepts

REST defines data exchanges between 2 entities as an "interop". An interface allowing the parties to follow an established contract in a conventional thus predictable way.

The terminology used here involves :

• Resources : similar to objects in OOP or tables in relational database : a group of data properties related to each other. Example : an Animal
• Operations : similar to functions or methods in coding. Example : Creating an Animal
• Ids : resource identifiers, can be of any type but has to be literal, and unique.

Key principles

Often when reading about REST, one land on [the well-known contraints](https://restfulapi.net/rest-architectural-constraints/) of REST architecture.

But I find those concepts hard to grasp, and way broader than API concepts. To keep things focused on our topic, I'll try here another approach, more focused on the contract between client and server.

Resource-identifiers URIs

In REST, the URI has to be meaningful, structured, and representing the resource we want to manipulate. In other words, the rule is to put the resource name in the URI.

Best conventions suggest resource names to be in kebab-case (hyphen separated lowercase), in their plural form.

One level down

The two basic shapes are single resources (identified by their Id) and resources lists :

Two levels down

An extended shape can express nested resources. Similarly to database foreign keys :

More levels down ?

I personally like to limit "nested-patterns" to 2 levels down; because further digging is a nonsense to me.

Indeed, imagine such a resource identifier :

Coding such a call requires you to know the end Animal id (21)...
so why not simply requesting it's toys ?

You can safely extrapolate that for any use-case : this kinda "resets" at any level. I personally never encountered a blocking use-case.
— But I'd love hearing in comments if you already did !

An exception ?

A decent exception use-case from what I just said are rare cases when you want to manipulate the association itself between 2 entities. In that case you need the 2 ids written down.

(We'll cover this case in a second with examples)

HTTP methods

Meaningfulness doesn't stops at resources, but also expands to operations. As such, in REST they are expressed using HTTP method verbs.

• GET is used to find or list
• POST is used to create (or sometimes "associate", see below)
• PATCH is used to update (partially)
• PUT is used to update (totally replace)
• DELETE is used to delete (or sometimes "dissociate", see below)

But with years, a common derogation arised

• PATCH is nowadays rarely used
• PUT is commonly used for partially updating instead

Let's review common use-cases by operation

GET use-cases :

POST use-cases

PUT use-cases

DELETE use-cases

Single-resource endpoints

As you already guessed, an important root principle of REST is that endpoints should manipulate a single given resource type. It means either a list of records of this resource type, or a single one record.

This applies to the body (both Response and Request) of operations :

GET /animals/23

{
  "id": 23,
  "breed": "dog",
  "name": "Skippy"
}

This returns the requested Animal object.

GET /animals

[
  { "id": 23, "breed": "dog", "name": "Skippy" },
  { "id": 24, "breed": "cat", "name": "Peanut" }
]

This returns the Animal list.

POST /animals

{
  "breed": "tiger",
  "name": "Sherkan"
}

{
  "id": 25,
  "breed": "tiger",
  "name": "Sherkan"
}

This takes an Animal — often without id if auto-generated
and returns the created Animal object.

PUT /animals/24

{
  "name": "Hazelnut"
}

{
  "id": 24,
  "breed": "cat",
  "name": "Hazelnut"
}

This takes an partial Animal — only properties to update
and returns the modified Animal object.

DELETE /animals/23

{
  "id": 23,
  "breed": "dog",
  "name": "Skippy"
}

Returns the deleted Animal object.

(Same logic goes for linked objects — that I exclude here for simplicity.)

HTTP Status codes

Again with meaningfulness in mind, responses should include standard and semantic HTTP status codes. This applies to both success and errors.

Success

• 201 - created : for every creation success (POST)
• 200 - ok : for every other success (GET, PUT, DELETE)

Errors

• 404 - not found : for inexisting objects (mainly targeted by resource/{id} routes, but also single linked objects resource/{id}/linked-object)
• 400 - bad request : for invalid bodies in creations or updates (POST, PUT)
• 409 - conflict
  • for already existing objects in rare cases when creating a resource directly with a forced id in body or URL (POST /resource/:id)
  • for already occupied association 1:1 when trying to created one (POST /resource/:id/linked-resource/:id)
• 410 - gone : means "deleted", for rare cases of requesting deleted object on servers tracking deleted objects (soft delete mecanism)
• 401 - unauthorized : for reserved resource when trying to access them without authentication
• 403 - forbidden : for reserved resource when trying to access them with unsufficient permission
• 500 - internal server error : for internal errors not to be shown to a user, or unknown errors
• 503 - service unavailable : for cases when the route is temporarily unavailable (external resource down, overload, etc.)

Wrapping up

As a sumup, applying the "Don't Reinvent the Wheel" principle, I propose you further readings that inspired me white writing this post.

RESTful Services Quick Tips

RESTful API or Web Service Quick Tips. Want to learn the high points of creating a REST API? Here’s the Web Services in 60-seconds version.

REST API TutorialTodd Fredrich, Pearson eCollege

REST Architectural Constraints

REST stands for Representational State Transfer, a term coined by Roy Fielding in 2000. It is an architecture style for designing loosely coupled applications over the network, that is often used in the development of web services. REST does not enforce any rule regarding how it should be implemente…

REST API TutorialLokesh Gupta

What are HTTP Status Codes? List Of Important Status Codes

An HTTP status code is a server response to a browser’s request. When you visit a website, your browser sends a request to the site’s server, and the server then responds to the browser’s request with a three-digit code: the HTTP status code. Common codes are: 1xx Informational requests, 2xx…

Moz

Architectural Styles and the Design of Network-based Software Architectures