Better Practices
Published in

Better Practices

Bringing law and order to APIs with OpenAPI Specifications

A better way to build and manage APIs using schemas, descriptions, and style guides

Photo by Lenny Kuhne on Unsplash

A brief history of API descriptions

Some confusing terms

it’s time to get pedantic

Schemas — this is how data looks

API description formats — this is a way to describe APIs

API description document — this is how a particular API works

API documentation — this is how to use a particular API

Example #1: Building blocks

DNA is the blueprint for every living organism

Example #2: Postman collections to describe an API

A Postman collection can be used as an API description format, API description document, or API documentation — depending on the context

Test APIs and lint specifications with OpenAPI Specification, Newman, and Spectral

Let’s run tests and lint specifications in our CI workflow

Step 0: Pre-requisites

$ npm init
$ npm install newman @stoplight/spectral

Newman — an open-source library by Postman for running Postman collections and tests

Spectral — an open-source JSON / YAML linter that supports OpenAPI Specification and JSON Schema

Step 1: Lint an OpenAPI specification file locally

Run the lint check using Spectral from the command line

Step 2: Generate a Postman collection from the OAS file

Import an OAS 3.0 specification and generate a Postman collection

Step 3: Write some Postman tests

Under the Tests tab, write Postman tests and save data as an environment variable to be used later

Step 4: Run the Postman tests locally

$ newman run Cosmos.postman_collection.json -e cosmos.postman_environment.json
Run the API tests using Newman from the command line

Step 5: Run tests and lint specifications in CI/CD

Run API tests and lint API specifications in a continuous integration workflow, like this example script
: {
"deploy": "./bin/"},...
$ npm run deploy

Step 6: Create a custom style guide

Create a style guide with your own custom linting rules, like this example

A final thought about API descriptions and linting

Don’t waste customers time forcing them to try and figure out your inconsistencies.

Don’t waste all API developers time learning to memorizing style guides.

Don’t waste the API governance teams time reviewing APIs manually.

Don’t waste everyone’s time fixing inconsistencies in production later.

- Phil Sturgeon, APIs you won’t hate



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store