7 essential tips for an efficient Node.js Rest API writing

Image source

Node is currently the most trending backend technology and one of the most popular usages is creating rest APIs. Rest APIs allows you to create dynamic web architectures as well as expose your services to other potential users, it’s an application interface at the end of the day, so it should allow other applications to talk to your application.

There are multiple practices to adopt and many common mistakes to avoid while creating your Node API. Node is a relatively young backend technology that is constantly under development and improvement, and it’s often not easy to write an optimized Node API.


#1 Use HTTP status code correctly

You have to use status code correctly all the time, whether it’s your application that is using the API or another application. It’s especially important to return appropriate status code when something goes wrong so that the applications could take the proper actions based on the returned status code.

Status codes should be something along the lines of:

  • 2xx if everything was ok
  • 3xx if the resources that were to be reached was moved elsewhere. They usually help to redirect to the current resource location.
  • 4xx If there has been a client error like a nonexisting URL or resource (404 anyone?)
  • 5xx if something went wrong on the server side

You can the full list of HTTP status codes here.

#2 Pick the right framework

Image Source

One of Node’s core strengths is that it ships with a powerful number of frameworks that make development not only easier but much more powerful and scalable all at once.

One current standard of Node development is Express, but alternatives include Koa and Hapi, they help you build full-scale web applications, from handling server-side business logic to rendering client views, they are quite often used to build Restful APIs as well.

However, Restify is a Node framework that aims to build strict Rest APIs, it aims to give you a full control over your HTTP communications and .

PerfectAPI is another framework which is said to be even 4 times faster than Restify while maintaining simplicity for both the users and the developers alike.

#3 Use JWT authentication

Image source

You’re using A representational state transfer API, and since you’re API is stateless, so should be the authentication process. Security is a major design parameter that should be taken into consideration. There are several authentication techniques to use with a Node API but token based authentications are ideal for an API.

The JWT consists of three parts:

Header which contains the type and hashing algorithm used

Payload Which contains the claim

Signature that is used to verify that the message wasn’t changed along the way.

You can learn more about JWT authentication here. The documentation is on point and it will

allow you to get a firm understanding of the technology.

#4 Avoid blocking functions

Blocking functions in Node are lethal poison, not for a single UX, but for the entire server. Since your node is strictly running on a single thread (unless you’re using Cluster) if the server makes one blocking function call, the entire thread will have to wait for it to execute. Now imagine if that function was a SELECT* From Users and the table contained a multiple thousand rows. Do you imagine how dreadful it is if you were at a bank, standing at an empty counter, yet unable to get served because the guy at the next counter is making a withdraw?

#5 use HTTP rate limiting

Rate limiting defines how many requests can a single user send to your server. It’s is a great way to fight against denial of services attacks like slow loris attacks. There are several HTTP headers that set the rate limit, define when to reset it, and point out the number of remaining requests. Most of Node frameworks are well-geared to implement rate limiting out of the box, additionally, you can use plugins as well.

#6 Test Your Node API as a black-box

It is by no means enough to just send status codes if something goes wrong. Proper testing in the software world is crucial, and one of the fundamental tests of an API is the black-box test.

The idea is to test your API like a user would use, to expose any potential errors or exceptions that the user might encounter and that might not be visible at the time of development. Testing the system as a whole can be done through modules like Supertest. You’d still have to make unit tests too - sorry to disappoint you- but black-box testing brings you closer to deployment.


#7 Create proper API documentation

You’re creating an API to be used, right? In most cases it will also be used by many other applications, so people should be able to wrap their head around the functionalities that your API provides. It’s impossible to know such functionalities without a proper documentation that illustrates (preferably with examples) how to use the API, what are the supported calls and the unsupported functionalities and such. A good documentation of your API will help more people use it in the long run.

#bonus Consider using HTTP2

HTTP2 is out and when it was tested, it was almost as twice as fast as HTTP 1.x. However, speed is not the only reason why you might want to use HTTP2. HTTP2 brings forth some very cool features like sending data in Binary format, header compression and using “Server Push” to speed up pages load time. Node currently supports HTTP2 and you can check out an example on how to launch your first HTTP2 test here. It’s not so different to using HTTP 1.x

Conclusion:

APIs are becoming a modern standard of the web that allows your applications and websites to gain more exposure and increase its users base. You can check some real life examples of famous web applications APIs such as GitHub or Stripe to gain inspiration. Check out programming community recommended best Nodejs tutorials and start learning rapidly. You’ll gain a lot of experience and learn a lot when you implement your own API using node, so get started and keep these best practices in mind!