API Guidelines

Human-readable API Guidelines

A human-readable version of the API Guidelines at Entur can be found here. The rest of this document describes how to do automatic checks on your API using a linter.

Linting your API

By "linting your API", we mean linting the OpenAPI specification of your API. This is done using Spectral with the Entur linting rules.

Adding the linter as a Github Action

gha-api linter

Running the linter on the command line, using Spectral CLI

Installing Spectral CLI

Using npm:
npm install -g @stoplight/spectral-cli

Or using yarn:
yarn global add @stoplight/spectral-cli

Running Spectral CLI

spectral lint api-spec.json --ruleset https://raw.githubusercontent.com/entur/api-guidelines/refs/tags/v0.1.0/.spectral.yml

Running the linter in your IDE

Spectral Linter for VS Code

Spectral Linter for Intellij : No good plugin seems to exist yet.

Running the linter using Git-hooks

Git hooks are programs or commands you can set up and have them run when you commit or push.

Here's an example of a Spectral Git hook using Husky:

{
  "husky": {
    "hooks": {
      "pre-commit": "spectral lint specs/*.{json,yml,yaml} --ruleset https://raw.githubusercontent.com/entur/api-guidelines/refs/tags/v0.1.0/.spectral.yml",
      "pre-push": "spectral lint specs/*.{json,yml,yaml} --ruleset https://raw.githubusercontent.com/entur/api-guidelines/refs/tags/v0.1.0/.spectral.yml",
      "...": "..."
    }
  }
}