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 others401 Unauthorized
Sent when authentication is required and the client is not authorized403 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.
→ I wrote 17 books to help you become a better developer, download them all at $0 cost by joining my newsletter
→ JOIN MY CODING BOOTCAMP, an amazing cohort course that will be a huge step up in your coding career - covering React, Next.js - next edition February 2025