5 best practices for building a modern API with Express

Last Updated: April 6, 2021

Express is relatively simple to get up and running. It also provides plenty of flexibility, making it a popular choice when choosing a framework to build an API with. Because of this, there are many tutorials and courses available which will teach you how to build an API with Express, however they can leave you uncertain about what best practices you should be considering for things like validation and error responses.

The following best practices will help you when designing a new API with Express, as well as with improving an existing one. Even better, these best practices will set you up with some features that other newer frameworks provide, but which aren’t included out-of-the-box with Express. Let’s get stuck in!

1. Enable the full use of promises and async / await
2. Validate request data with JSON Schema
3. Use an existing format for error responses
4. Send CORS response headers so web pages can call your API
5. Separate your concerns

Express technically works fine if you use promises and async / await in your middleware or route handlers. However, you must write extra code to catch the error that gets thrown when an awaited promise rejects, and then you must call the next() function with that error. If you don’t, the request will likely hang and no response will be sent to the client. This can can get quite messy and is easy to forget about.

There are two different packages which you can use to add support for async code to your Express application:

• express-async-errors – This package monkey patches the internals of Express to add support for promises. It doesn’t need any configuration: just require it after express and you’re good to go.
• express-async-handler – If you don’t like the idea of monkey patching the internals of Express, this package takes a different approach approach: it provides an asyncHandler() function which you can use to wrap all middleware and route handler functions.

Both of these packages will allow you to write code in your Express applications which uses promises and async / await, with much less risk of uncaught promise rejections occurring.

You can learn about what’s needed to be able to write async code safely in my article Are you using promises and async / await safely in Node.js?.

You should never just trust data which is is sent in a request to your API as it could easily contain mistakes, or worse it might contain malicious data which has been crafted by an attacker in an attempt to crash your application or steal data. This means that you should always validate any data which is sent to your API before you do anything else with it e.g. store it in a database.

JSON Schema is an established standard which you can use to describe the format that you expect data to be in – a "schema". If data fails validation against a schema you will be provided with detailed error messages which you can then pass on to the client in your API response. JSON Schema is very powerful, allowing you to create schemas which validate complex data structures, however a schema could be as simple as checking that a piece of data is a string, with a schema like this:

The express-json-validator-middleware package brings support for JSON Schema into your application. It enables you to validate requests to your API against any schemas that you define and configure it to use.

If you want to learn how you can use JSON Schema to validate requests in your Express API, I’ve written an article which shows you how.

It’s very tempting when building an API to invent your own format for error responses, but HTTP response status codes are a great starting point as they can communicate a specific error state. If you need to provide additional context beyond this about why the error occurred – and perhaps what can be done to resolve the issue, in the case of a client error – it’s worth considering applying the Problem Details specification. It’s a specification for an error response format from HTTP APIs, meaning that you don’t need to come up with your own. Here’s an example response using this format:

The Problem Details specification is covered in RFC7807 – Problem Details for HTTP APIs.

You can learn how to create and send Problem Details error responses in my blog post Send awesome structured error responses with Express.

If you want front end JavaScript on a web page to be able to make requests to your API, you’ll typically need your API to send CORS (Cross-Origin Resource Sharing) headers in the response. These headers tell web browsers whether it is ok or not for the web page making the request to access the contents of the API response.

You can add the cors middleware package to your application to help you send the correct CORS response headers from your API endpoints. By default, the headers it sends will allow any web page to make requests to your API, so make sure you check out the configuration options, and at the very least set the origin option so that you are restricting which web pages are able to call your API (unless you’re running an API for public use, in which case this won’t be an issue).

I’ve written a handy guide to what CORS is, how it works and how to integrate the cors middleware into your application: How to fix those confusing CORS errors when calling your Express API.

This is an important design principle to apply when building any type of software: split up your code into distinct modules, with single purposes and well defined interfaces. When building an API with Express it’s easy to make the mistake of mixing multiple concerns in a single module e.g. Express app configuration, route definitions, route handler middleware, database calls. Just because you can do this definitely doesn’t mean that you should! Building an application in this way will make your code much harder to test, debug, maintain and extend in the future.

If you want to see what a clear separation of concerns can look like for an Express based API, sign up to my mailing list and I’ll send you a link to the code for an example application which demonstrates this.

It is certainly possible to refactor your application later on and separate the concerns, but if you can consider how you want to do this early on, while planning and designing your API, it will result in a much more stable foundation for future development.