Lint CAMARA APIs

This guide sets up apigenie lint for a repository of the CAMARA project: the configuration, the first run on an API, and the check on every pull request. It uses the layout of a CAMARA API repository: the APIs in code/API_definitions/, and the common files they reference in code/common/. The camara ruleset is in API Genie since 0.12.0.

You need the CLI installed; the Quickstart shows how.

Configure the repository

Put an apigenie.yaml at the root of the repository:

# yaml-language-server: $schema=https://apigenie.pl/schemas/apigenie-config/latest.json
version: '1.0'
commands:
  lint:
    extends: [camara]
    bundle: true
  • camara is the ruleset CAMARA lints with for Commonalities r4, its .spectral-r4.yaml with its 41 rules and 14 JavaScript functions. It ships with API Genie, so the repository needs no copy.
  • bundle: true brings the common files an API references, such as ../common/CAMARA_common.yaml, into it before the rules run. An issue found in a common file is reported in that file, at its line.

Lint an API

Run the linter from the root of the repository, which is where it finds apigenie.yaml:

apigenie lint code/API_definitions/quality-on-demand.yaml
/home/me/QualityOnDemand/code/common/CAMARA_common.yaml
  135:9  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted
  139:9  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted
  182:5  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted
/home/me/QualityOnDemand/code/common/CAMARA_event_common.yaml
  52:9  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted
  58:9  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted

  5 issues (0 errors, 5 warnings)

Each line gives the position, the severity, the message and the rule. The API passes every camara-* rule. The 5 warnings come from the OWASP rules CAMARA’s file turns on, in the common files the API references. A CAMARA rule keeps its id, such as camara-properties-descriptions, so CAMARA’s documentation of it still applies. Errors make the command exit with status 1. --fix ignores bundle: true: it lints and fixes each file as it is.

Lint every API of the repository at once:

apigenie lint code/API_definitions/*.yaml
/home/me/QualityOnDemand/code/common/CAMARA_common.yaml
  135:9  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted
  139:9  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted
  182:5  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted
/home/me/QualityOnDemand/code/common/CAMARA_event_common.yaml
  52:9  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted
  58:9  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted

  5 issues (0 errors, 5 warnings)

/home/me/QualityOnDemand/code/common/CAMARA_common.yaml
  135:9  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted
  139:9  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted
  182:5  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted
/home/me/QualityOnDemand/code/common/CAMARA_event_common.yaml
  52:9  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted
  58:9  warning  Schema of type string should specify a format, pattern, enum, or const.  owasp:api4:2023-string-restricted

  5 issues (0 errors, 5 warnings)

The repository has two APIs, quality-on-demand.yaml and qos-provisioning.yaml, and both reference the same common files. Each API is linted on its own and gets its own report, so the 5 warnings in the common files appear twice, once for each API.

Add API Genie’s own checks

CAMARA’s file also extends Spectral’s spectral:oas rules, which API Genie doesn’t have. API Genie’s recommended ruleset has counterparts of about two thirds of them, and checks of its own that CAMARA’s run doesn’t make:

commands:
  lint:
    extends: [recommended, camara]
    bundle: true

Expect more findings: on quality-on-demand.yaml this reports 141 issues, 64 of them errors, where extends: [camara] alone reports 5 warnings and no errors. Turn off under rules what your team doesn’t follow.

Change a rule

rules changes a CAMARA rule as it changes any other, by its id. Turn one off, or change its severity:

commands:
  lint:
    extends: [camara]
    bundle: true
    rules:
      camara-operationid-casing-convention: off
      camara-path-param-id: error

[camara, all] in extends also applies the two rules CAMARA’s file leaves off: the deprecated camara-discriminator-use, and camara-language-avoid-telco, which reports nothing.

Add the check to pull requests

The GitHub Action installs the CLI and runs apigenie lint with the repository’s apigenie.yaml. Add it to a workflow in .github/workflows/:

on: pull_request
jobs:
  api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mykulyak/api-genie-action@v0
        with:
          command: lint
          files: code/API_definitions/*.yaml

The step fails when an error is reported, and each issue shows as an annotation on its file in the pull request. With several APIs, a warning in a common file shows once for each API. On QualityOnDemand the step passes: it reports only the 5 warnings.

The step runs CAMARA’s Spectral rules with no Node.js and no ruleset fetched from camaraproject/tooling. CAMARA’s other checks, its Python checks, yamllint and Gherkin lint, stay where they are.

To send the issues to GitHub code scanning instead, run the GitHub Action without command, which only installs the CLI. Then write the report with the SARIF formatter and upload it with github/codeql-action/upload-sarif.

What differs from CAMARA’s Spectral run

On the two APIs of QualityOnDemand, Spectral 6.17.0 with .spectral-r4.yaml and API Genie with extends: [camara] report the same 5 warnings at the same lines. Both exit with status 0. They print them differently:

  • Spectral reports a column after the key, 135:14 for the first warning; API Genie reports the key’s first column, 135:9.
  • Spectral prints a common file once per run. API Genie prints a report for each API, so a common file appears once for each API that references it, as in the output of the second command.

In a repository whose APIs trip the spectral:oas rules that CAMARA’s file extends, Spectral reports those issues and API Genie doesn’t: it doesn’t have those rules, and says nothing about skipping them. The one exception is operation-success-response, which CAMARA’s file turns on and API Genie has under that id. recommended has counterparts of about two thirds of the others.

The editor and the VS Code extension don’t run the ruleset’s JavaScript functions. There, extends: [camara] is an error that begins Unknown ruleset camara, and the default rules apply.

Next steps

Last updated on Edit this page on GitHubView as Markdown
Was this helpful?