APIs With Node.js and Express: Automatically Validate API Requests Using an OpenAPI 3 Specification

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.

In this article, we’ll see how an OpenAPI specification can be used to automatically validate API requests. 

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 and 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:

  1. Require express-openapi-validator — a package to automatically validate routes defined in Express against an OpenAPI 3 spec
  2. Install the OpenApiValidator onto our express application
  3. 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.

The express-openapi-validator lives here.

Thanks for reading ❤

If you liked this post, share it with all of your programming buddies!

Follow me on Facebook | Twitter

Learn More

The Complete Node.js Developer Course (3rd Edition)

Angular & NodeJS - The MEAN Stack Guide

NodeJS - The Complete Guide (incl. MVC, REST APIs, GraphQL)

Node.js: The Complete Guide to Build RESTful APIs (2018)

Learn and Understand NodeJS

MERN Stack Front To Back: Full Stack React, Redux & Node.js

Learn Node.js - Node.js API Development for Beginners

Moving from NodeJS to Go

How to Perform Web-Scraping using Node.js

Node.js, ExpressJs, MongoDB and Vue.js (MEVN Stack) Application Tutorial

Top 10 Node.js Frameworks

Angular 9 Tutorial: Learn to Build a CRUD Angular App Quickly

What's new in Bootstrap 5 and when Bootstrap 5 release date?

Brave, Chrome, Firefox, Opera or Edge: Which is Better and Faster?

How to Build Progressive Web Apps (PWA) using Angular 9

What is new features in Javascript ES2020 ECMAScript 2020

How to Build a RESTful API in Node.js, Express.js & MongoDB (Mongoose)

How to Build a RESTful API in Node.js, Express.js and MongoDB (Mongoose). Learn to create your first RESTful API in NodeJS, ExpressJS, and MongoDB (mongoose). We cover the MVC pattern, CRUD, Routes, Error Handling, ES6, Promises, GET, POST, DELETE in under 50 minutes. Learn to build a REST API to create,modify and delete users in a database. Build a simple API using ExpressJs and MongoDb with CRUD functions for Contacts.

Creating a RESTful Web API with Node.js and Express.js from scratch

In this article, I’ll show you step by step how to create a RESTful Web API with Node.js and Express.js by building a simple and useful Todo API. This article assumes you have basic javascript knowledge and terminal using capabilities.

Build a REST API using Node.js, Express.js, Mongoose.js and MongoDB

Node.js, Express.js, Mongoose.js, and MongoDB is a great combination for building easy and fast REST API. You will see how fast that combination than other existing frameworks because of Node.js is a packaged compilation of Google’s V8 JavaScript engine and it works on non-blocking and event-driven I/O. Express.js is a Javascript web server that has a complete function of web development including REST API.