# Lint CAMARA APIs Source: https://apigenie.pl/docs/guides/industry/lint-camara-apis This guide sets up `apigenie lint` for a repository of the [CAMARA project](https://camaraproject.org): 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`](/docs/reference/cli/lint#the-camara-ruleset) ruleset is in API Genie since 0.12.0. You need the CLI installed; the [Quickstart](/docs/quickstart) shows how. ## Configure the repository Put an `apigenie.yaml` at the root of the repository: ```yaml # 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`](/docs/reference/cli/lint#configuration) 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`: ```sh apigenie lint code/API_definitions/quality-on-demand.yaml ``` ```text /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: ```sh apigenie lint code/API_definitions/*.yaml ``` ```text /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: ```yaml 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: ```yaml 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](/docs/ci/github-action) installs the CLI and runs `apigenie lint` with the repository's `apigenie.yaml`. Add it to a workflow in `.github/workflows/`: ```yaml 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](https://github.com/camaraproject/tooling/tree/main/linting/config). 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](/docs/ci/github-action) without `command`, which only installs the CLI. Then write the report with the [SARIF formatter](/docs/reference/cli/lint#sarif) 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 - [The `camara` ruleset](/docs/reference/cli/lint#the-camara-ruleset) and the [`owasp`](/docs/reference/cli/lint#the-owasp-ruleset) ruleset it extends. - [Migrate from Spectral](/docs/guides/migrate-from-spectral), for a repository with rules of its own. - [Catch breaking changes in CI](/docs/guides/catch-breaking-changes-in-ci), to rate what each version of an API changes for its clients.