These days, I’ve been working on writing an API in Node.js. Like any other developer, I’ve taken some code from past projects and also I’m taking the time to explore some new strategies and ways to organize the code and the documentation in order to make it understandable in terms of an API.
I got some interesting insights and wanted to share with you all some tips for building an API that worked for me in this project and in a few more in the past.
When I started using Node.js my code was something similar to this:
You and I know that this way to start building an API and have something working is very fast. But… there are some problems related to this structure.
- Unless you split it in modules, it will become a long long file.
- As the file is getting longer, it becomes harder to read and understand what’s going on with the API.
- It’s also hard to identify the resources and their methods, apart of the long file, they can be mixed al along the code.
I use express as the web framework, and one of the most noticeable things about it, when you are coming from another framework, is the lack of structure. I mean, it’s great that the concepts are well explained, and the flexibility is awesome, but some things like building an API can lead to a lot of ends… I’m no one really knows which one is the best.
This last time, I used a structure similar to this.
Where basically every file is a module that exports a middleware that handles the request but only performs the logic related with one of the HTTP verbs.
I also use the index file to organize the API routes and require the modules.
This way, I can easily see my routes in a single file and, if I need to do a change for a specific route/verb I know exactly where to look.
For the routes definition, a good idea is to use the express Router, in my opinion, improves the readability a lot.
In case you want to distribute your API, even internally, in a future moment, you’ll need documentation. If you are working alone you might think “meh, I wrote this thing, I’ll remember it forever” Do a favor to yourself and write at least a bit of documentation about your resources, payloads, and responses.
For my last API, I used http://apidocjs.com/ This tool allows you to write documentation as comments in the code and then process them to generate an HTML page with the information about your API.
I was working on an internal API, so in my case is good enough for the level of documentation that I needed. I’m not sure if it’s good enough for public APIs, but if you are going to release a public API, I’m totally sure that you’ll spend more time on documentation 😉
The power of middlewares
In case you are a beginner or even someone that usually doesn’t use middlewares, please start using them.
You can use middlewares for authentication, validation, response formatting, etc. In my case, I validate some headers for authentication and custom settings for requests, just to make sure everything is prepared before the logic inside my resources is executed.
The level of code re-utilization that you can achieve with the strategy is very high. Please don’t waste the chance to write less code and increase security and stability in your API.
I hope that these tips or strategies help you with your own project. As always, if you have any question or you’d like us to write about any other topic, just let us know.
Regos Dev Studio is a product development company that builds add-ons for Jira, Confluence and LiveChat, combined with development of custom solutions in a variety of languages.