Why is RESTful API so popular?

If you prefer video, full video available here:

REST is the most common communication standard between computers over the internet. What is it? Why is it so popular? 

The common API standard used by most mobile and web applications to talk to the servers is called REST. It stands for REpresentational State Transfer.

REST is not a specification. It is a loose set of rules that has been the de facto standard for building web API since the early 2000s.

An API that follows the REST standard is called a RESTful API. Some real-life examples are Twilio, Stripe, and Google Maps.

Let’s look at the basics of REST. A RESTful API organizes resources into a set of unique URIs or Uniform Resource Identifiers.

The resources should be grouped by noun and not verb. An API to get all products should be

A client interacts with a resource by making a request to the endpoint for the resource over HTTP. The request has a very specific format. 

POST /products HTTP/1.1

The line contains the URI for the resource we’d like to access. The URI is preceded by an HTTP verb which tells the server what we want to do with the resource.

You might have heard of the acronym CRUD. This is what it stands for.

In the body of these requests there could be an optional HTTP request body that contains a custom payload of data, usually encoded in JSON.

The server receives the request, processes it, and formats the result into a response.

The first line of the response contains the HTTP status code to tell the client what happened to the request.

A well-implemented RESTful API returns proper HTTP status codes.

A well-behaved client could choose to retry a failed request with a 500-level status code.

We said “could choose to retry” because some actions are not idempotent and those require extra care when retrying. When an API is idempotent, making multiple identical requests has the same effect as making a single request. This is usually not the case for a POST request to create a new resource.

The response body is optional and could contain the data payload and is usually formatted in json.

There is a critical attribute of REST that is worth discussing more.

A REST implementation should be stateless. It means that the two parties don’t need to store any information about each other and every request and response is independent from all others.

This leads to web applications that are easy to scale and well-behaved.

There are two finer points to discuss to round out a well-behaved RESTful API.

If an API endpoint returns a huge amount of data, use pagination.

A common pagination scheme uses limit and offset. Here is an example:

If they are not specified, the server should assume sensible default values.

Lastly, versioning of an API is very important.

Versioning allows an implementation to provide backward compatibility so that if we introduce breaking changes from one version to another, consumers get enough time to move to the next version.

There are many ways to version an API. The most straightforward is to prefix the version before the resource on the URI. For instance:

There are other popular API options like GraphQL and gRPC. We will discuss those and compare them separately.