Build an API with Node.js: Automatically validate API requests using an OpenAPI 3 specification

Carmine DiMascio — Tue, 26 Mar 2019 14:01:08 +0000

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!

DEV Community: Carmine DiMascio

Build an API with Node.js: Automatically validate API requests using an OpenAPI 3 specification

Create an Express application for our simple API

Create an OpenAPI spec to describe our API

Integrate automatic request validation with Express-OpenAPI-Validator

Try it out