Introduction to building REST APIs
By: Raphael Noriode
Tags: API, Nodejs, JavaScript, Rest Api, Backend Development

REST is a client-server architecture, it leverages the HTTP protocol, REST stands for representation state transfer, it is an architectural style for distributed hypermedia systems.

In order for an API to be considered as RESTful, it needs to meet six crucial criteria

Client-Server

Uniform Interface

Cacheable

Stateless

Layered System

Code on Demand (optional)

An example of a REST API is the GitHub REST API v3, it is completely client to server, that is the client is separate from the server, client in the traditional sense is usually referred to as the browser but for an API the client would be anything making the API request, so right now if I decide to call the GitHub API as you would see shortly, my server becomes the client to the Github server. It has a uniform interface as the server announces available actions beforehand. Statelessness means that every HTTP request happens in complete isolation, the server doesn’t pass state between requests so the next request is completely independent of the previous one.

Calling an API

Here I will be using Postman to interact with the Github API

From the JSON data returned, we see multiple endpoints that can be used to access other resources, basically, that is what a uniform interface would entail.

Good to know

When building a REST API, resources should be nouns and not verbs, so instead of having endpoints like this

/getallusers or /createuser

you should have

/users

leveraging the HTTP request methods as verbs you would be able to accomplish multiple tasks with correct semantics.

2. CRUD

CRUD is simply the standard way of using HTTP action verb it stands for create, read, update and delete. So to make a create action you use the post verb, for a read action you use the get verb, for an update action you use the put or patch verb, for a delete action you use the delete verb.

3. You should normally serve more than one content type, that is your API should be able to return JSON, XML, text e.t.c but for the purpose of simplicity in this tutorial, the API would return only JSON data.

Building your own REST API

In this tutorial, I would use Nodejs and express to create our server. Below is the basic setup of a node web server using express

For the purpose of this tutorial, I will use a mock database called fancyRecords, created with javascript objects, to mimic a relationship between car owners and their cars, I know it’s lame but stick with me. Imagine this is a database of cool kids in your neighborhood with very good wheels

Our Read endpoints

From the beginning line 1–11 our API basically serves out all the possible endpoints that a client would need, basically maintaining a uniform resource and being stateless, although this is an overkill for this demo, it explains little about those two points but you should get the idea. Just make life easy for your client.

The output of the get routes

Get all routes available in the fancyRecords API

Now we would check out all the routes and see the outputs

GET all the car owners (localhost:3001/fancyrecords/owners)

GET all the cars (localhost:3001/fancyrecords/cars)

GET a car owner (localhost:3001/fancyrecords/owners/:ownerId)

GET just one car (localhost:3001/fancyrecords/cars/:carId)

GET all cars of an individual owner (localhost:3001/fancyrecords/owners/:ownerId/cars)

Can we add data? If our API is built specifically for a web client, we would likely need to send data through it to the database, as an extension of a need to use nouns as resources we would see that the routes do not change, all we need to do is change the HTTP request method from Get to Post, with a bit of logic and we are fine.

Sending data through the API

This API receives data to the owners and cars endpoints only, we can add a new user and add a new car. In order for an API to be considered truly RESTful, it should accept more than one content type but for simplicity sake, we would only be using JSON data, normally a web client would send in form data, so keep that in mind.

Post (localhost:3001/fancyrecords/owners)

The content added to the database was returned, this is not standard, just for clarity. You usually want to return a success or failure notice depending on the outcome.

Deleting

It turns out one of the owners in the fancyRecords’ DB is a fraud, he doesn’t really own two cars, he pulled a good stunt on all of us. The good thing is we can wipe all his record with the HTTP delete verb by accessing an owner’s endpoint. localhost:3001/fancyrecords/owners/:ownerId

So when a car owner is deleted we want to delete all the associated records, in this case, all the cars he owns or claims to own, LOL.

From the output returned you can see that all records of that car owner were deleted Malam Musa is no longer one of the cool kids.

Updating

Adhering to CRUD, we should be able to update a record, let’s do that.

So, it turns out the Volkswagen Beetle is actually a BMW i8, no one knows how the mistake was made, but thankfully we can update that.

So far so good we have covered CRUD

Idempotence

For an API to be idempotent client can make the same call to it and receive the same result. Idempotent operations may produce the same result on the server, but the response itself may not be the same. The Get, Put and Delete HTTP operations are generally considered as idempotent.

Conclusion

RESTful APIs are awesome, they are easy to interact with, maybe not easy to build but we should always design APIs with the client in mind if it is easy enough for the client then it is good enough. If you want to check out the complete code here is a link to it.

Please leave a comment if you feel anything is off, let’s talk about it.