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.
First let’s create a simple Express application.
Running the above code launches an API server that exposes the following routes:
Note: The APIs return values are contrived and not relevant to this tutorial.
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.
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…
Let’s execute some API requests with curl and observe the automatic request validation in action.
Let’s try GET /v1/pets
Let’s try POST /v1/pets
The full source code for this example can be found here.
If you dig express-openapi-validator,
Star it on Github!