Express js
is a Node.js web application framework
which is excellent for
Rest API
development and is based on JavaScript. I won’t write the generic info
on express in this article which you might find by simply hitting Express js API in the search tab. Instead, I would like to do the next 2 big things:

REST API structure. How to set up REST API correctly?

REST API development is the ‘description of routes’ by which
client-devices or other services refer to your server. That’s why it's important to organize you REST API properly and make these ‘routes’ intuitive.
Consider it as a map. Large REST API server performs lots of operations.
The most common mistake among REST API developers is that they create a
separate route for each operation and don’t record it properly. The result
is an uncontrolled increase of routes which eventually causes timing and
knowledge obstacles on the way to understand your API.

What I want to say in this REST API tutorial, is to include these requests into each operation.
For example, if you need to update any entity, use UPDATE requests if
delete - DELETE requests. Another tip is to correlate each route to the
business logic model.

Take a look at the table below with 5 routes to process single business
logic model. Consider it as the example of using REST API.

Route

HTTP Verb

Description

/api/v1/models/

GET

Get list of models

/api/v1/models/:modelId

GET

Get model item

/api/v1/models/

POST

Crete model Item

/api/v1/models/:modelId

PUT

Update model Item

/api/v1/models/:modelId

DELETE

Remove model item

The table shows us the routes variations and corresponding methods
aimed to provide CRUD (create, read, update, delete) requests to process a
certain model. If you keep to this strategy for each model processing and
don’t create additional routes, as described in this REST API guide, your API will instantly get understandable
and clear.

Parameters

What about additional parameters? We want
to return sorted and filtered models list. There’s no need to create an
additional route, like /api/v1/models/sorted/:param.

Using of query parameters should be enough, and after their implementation, the
route will look like: /API/v1/models?sort=name.

There may be a lot more of such parameters. They're not necessary but using query parameters will help you perform several
operations on a single route.

Although, such technique might seem tedious if you implement it for the client-side development, it's not. Below you’ll find some practical
examples.

Code organization tips

In this Express js API guide, I want to share the most helpful coding tips when I'm on my way to set up Express js API.

Start each route as /api/v1/. Don’t exclude the future possibility of
rewriting the current API by preserving the functionality of the old one
for some time.

Separate models from controllers. Models are business logic objects, and they
should be stored in the models folder. Controllers contain routes business
logic and should refer to controllers folder.

Don’t place routes of the same model in one file. It's better to create a
separate modelName folder for each entity and create a separate file for each GET,
POST, DELETE operation. For instance, file
controllers/notifications/index.js can look like this:

REST API documentation

Take care of proper documentation records as it’s a vital part of the REST
API development process and Express js API organization. Since such API might be requested by other
developers (front-end, mobile developers) or 3rd party services, clear
guidelines on how to interact with your API is a must have. To clarify
everything on the spot, I would recommend doing the following:

Before creating any documentation, determine what is the purpose of this
API and who will use it. For the projects with internal
API, you can record the routes both in README files of the repository and
in the controllers/model/index.js files. Find the documentation example
below:

If it’s an API meant for external use, you should think of creating a
complete, sorted and convenient in use reference/documentation. Here, take a
look how
Google Calendar API
is managed. Another great example of using REST API.

Keep documentation reference for each of your routes. There’s no reason in route existence if
nobody knows about it. If your API users don’t have enough information,
they can decide that you simply don’t support such functionality. That’s
why again, I put a high emphasis on keeping each route documented since it's aimed at making your REST API organization better

Record the route at the moment of route creation. Don’t ‘I’ll do it
tomorrow’ since you can simply forget about it or its parameters.

REST API Error handling techniques

REST server has a large list of default
HTTP Status Codes
(default errors included), so you don’t have to figure out your own error
types. The advice is, it's better to write your own events processor and use it
everywhere than do it for each router. For this, here comes the helping
hand of
rest-API-errors
package. But before implementing the package, you should write a
general processor:

Permission checker

In this part of our REST API guide I'll touch upon permission levels with providing an example of using Express js API.
There’s often a need to provide separate permission levels for different
user groups. Managers, for instance, could have more rights than regular users.
The following snippet represents how to write compact permission
checker which looks like this:

In the current example, the user has roles field ['owner', 'user'] , which
points to what role he/she has. When user gets owner role which has
GET_USER permission, then hasPermissionTo returns true value. You can also
create your own logic of hasPermissionTo method.

Client requests

You can organize client requests by different means and with the help of
different libraries. Here’s my personal insight on how to organize the process
properly.

Keep routes and codes at a distance. Don’t even think (seriously) of
hardcoding endpoint path directly in code that performs request:

axios.get('api/v1/users', {
params: {}
})

Why do I insist on this? When you change something in the API, it will cause
troubles looking for the routes in code. According to our own experience,
it’s better to write storages for each route and keep them in one place,
like this:

APIAddresses is imported and exported to make importing from a single
source easier.

Following the current logic organization strategy, given in this example of using Express js API, you’ll get rid of
unnecessary code snippets and improve the API concept for other developers or services overall. Take into account that if you change or update
the API version, changing routes in one file will be enough.

Wrapping up

Every project is different in its idea and needs. I understand that it’s
not always possible to keep up to a single development pattern, but any
kind of personal experience can give light to a lot of things.

Let’s shortly summarize the main ideas of the entire REST API tutorial:

Keep to REST logic

Organize Express js API (routes, events processing and permissions)

Keep documentation on your API

Organize your requests to avoid code duplications.

The correct organization techniques of your REST API will definitely reduce
the development time and improve the overall quality of your project. Hope this Express js API tutorial will help you.