An introduction to REST APIs

What is a REST API from the point of view of a creator of a REST API and from the point of view of a consumer

API stands for Application Programming Interface, and it’s an umbrella term that identifies different things.

We saw how the browser can offer some APIs, in the form of functions available to us.

We saw how Node.js offers us a programming API with its default modules.

API also means another thing: creating a service that exposes some specific functionality, provided through a server that can be accessed by multiple clients.

Broadly speaking, we currently have 2 categories of APIs: REST APIs and GraphQL APIs.

Other kinds of API paradigms exist, like SOAP for example, but they are not very popular in the JavaScript world.

In this post we’ll talk about REST APIs.

Endpoints

In a REST API, we create a number of endpoints that a client can access.

Say we want to expose a list of people. We can create an endpoint that will respond to the /people route.

If our service listens on the domain test.com, we’d have the test.com/people URL.

This endpoint will provide data in any format, but generally we use JSON, a handy text-based format used to communicate data between two services.

This /people endpoint can provide a list of names of people, and an id for each person. This might be the id that we use to store them in the database, for example.

Our system can also expose another endpoint, which we can call /person. This accepts an id that uniquely identifies a person, like this: /person/1

Our API will provide more information about that person, for example age, email, address.

The important thing to note is that in the first endpoint we didn’t have any parameter, but this time we have one.

Parameters can be sent in different ways, and not all the endpoints will be used to send information from the server. Some other endpoints will be used to perform actions, as we’ll soon see.

Methods

I mentioned that the /people endpoint will return the list of people in our system.

This was a simplification, and it’s time to dig deeper.

A REST API uses the HTTP protocol principles to provide different functionality based on the HTTP method used: GET, POST, PUT, DELETE.

GET is the most common one. When a client calls our API endpoint with a GET method, it signals that it wants to read data.

GET /people will return a list of people.

GET /person/1 will return a person details.

When the HTTP method is POST, the meaning is completely different. The endpoint will be the same, but the action required will be another one.

We, as API builders, define what hte meaning is.

For example we might create a POST /person endpoint that when called creates a new person in the database.

It receives data from the client, in a predefined format that we can choose. We’ll soon see an example made using Express.

GET and POST are the main 2 verbs used.

Sometimes we use PUT and DELETE: PUT is sometimes used to update a resource, like changing the address of a person. DELETE is used to remove a resource.

Other times, POST is used for everything that is not reading, where GET is used.

We have freedom in this choice.

By resource we mean an entity, like people in the plural form in the case of /people, or a single person in the case of /person.

Naming API endpoints

Look how I used /people and /person above.

Those are nouns.

Using nouns for endpoints, and using HTTP methods for signaling the action, is considered a best practice.

Updating a person uses a POST request to the /person endpoint.

If you want to create an API to send a message to a person, you’d make a POST request using a /message endpoint, passing data to it to identify the person and the message you want to send.

A REST API is stateless

A REST API is stateless.

This means it does not have any memory between different requests.

Most APIs you can find implement an API Key mechanism that serves as a way to track who is calling an API, and provide a way to monitor usage and force limits.

An API can also be protected using a login/password mechanism. In this case an API authentication process will need to take into consideration an handshaking process that provides a token that then needs to be sent in every future request, to identify the user and the correct authorization.

Responses

An API call will return a response to the user, in 2 forms: an HTTP response status code, and an HTTP response body.

Every HTTP request has a status code.

We have some conventions regarding the HTTP response status code: when you use the browser to open a web page, the page will return a 200 OK status code. If the page is not found, a 404 NOT FOUND status code.

The same works for our APIs.

Common ones are:

• 200 OK: this is the standard response for successful HTTP requests.
• 201 Created: Typically a response to a POST request. The request has been completed, and a new resource has been created.
• 400 Bad Request Due to a request error that was generated on the client, the server cannot process the request. Errors can include a malformed request, size too large to be handled, or others
• 401 Unauthorized Sent when authentication is required and the client is not authorized
• 403 Forbidden The resource is not available for various reasons. If the reason is authentication, prefer the 401 Unauthorized status code.
• 404 Not Found The requested resource could not be found.
• 405 Method Not Allowed The resource is not available through that HTTP method, but might be with another.
• 500 Internal Server Error A generic server error message, given when an unexpected condition was encountered and no more specific message is suitable.

You can find the full list on The HTTP Status Codes List. The thing to note is that when you create an API you should always return the correct status code, to inform your clients.

The response body is usually a JSON response with the data that was requested, or an error message.

The details of how the message is built is decided by you, API builder, or by who built the API.