APIs with Node.js and Express: Automatically validate API requests using an OpenAPI 3 specification
Web APIs are central to today’s applications. They provide interfaces that are easily consumed by apps written in any programming language on any platform. They make complex technologies simple by exposing easy-to-use, intuitive interfaces that enable app developers to weave together incredible experiences quickly.
To leverage and understand an API, documentation becomes a critical necessity. Specifications like OpenAPI 3 enable APIs to be described in a standard format that can easily be rendered e.g. as interactive, HTML documentation.
In this article, we’ll see how an OpenAPI specification can also be used to automatically validate API requests!
We’ll build the API server using Node.js and Express. We’ll utilize express-openapi-validator to automatically validate API requests using an OpenAPI 3 specification.
Let’s get started.
Create an Express application for our simple API
First let’s create a simple Express application.
Running the above code launches an API server that exposes the following routes:
- GET /v1/pets
- POST /v1/pets
- GET /v1/pets/:id
Note: The APIs return values are contrived and not relevant to this tutorial.
Create an OpenAPI spec to describe our API
Now that we have written our simple API, let’s add some validation. BUT, instead of writing a bunch of validation code, we’ll describe our API by creating an OpenAPI 3 specification.
(I’ll assume you know how to create an OpenApi spec, hence I’ll describe only the relevant snippets. If you’d like to see the full spec, go here).
Let’s make it a requirement that requests to GET /v1/pets must provide the query parameter, limit. Let’s also require that limit be an integer with a value greater than zero.
Let’s also make it a requirement that requests to POST /v1/pets must provide a JSON body containing a required field, name.
We’ll also add the NewPets component to our OpenAPI 3 spec.
Integrate automatic request validation with Express-OpenAPI-Validator
Finally, we’ll make a few minor code adjustments to enable our API server to automatically validate API requests using our OpenAPI 3 specification.
The code adjustments include the following:
- Require express-openapi-validator — a package to automatically validate routes defined in Express against an OpenAPI 3 spec
- Install the OpenApiValidator onto our express application
- Provide an Express error handler to customize our error responses
After making these changes, our final code is as follows:
(Note, steps 1, 2, and 3 indicating the new code that’s been added)
Start the server, then…
Try it out
Let’s execute some API requests with curl and observe the automatic request validation in action.
Let’s try GET /v1/pets
Returns:
Let’s try POST /v1/pets
Returns
The full source code for this example can be found here.
If you dig express-openapi-validator,
Star it on Github!
