Adafruit IO · API Governance Rules

Adafruit IO API Rules

Spectral linting rules defining API design standards and conventions for Adafruit IO.

8 Rules error 1 warn 5

View Rules File View on GitHub

Rule Categories

adafruit

Rules

error

adafruit-io-https-only

All servers must use HTTPS.

$.servers[*]

warn

adafruit-io-base-path-v2

API base path must start with /api/v2.

$.servers[*]

warn

adafruit-io-username-scoped

Every account-scoped path must be parameterized on {username}.

$.paths[?(@property != '/user' && @property !~ '^/webhooks')]~

warn

adafruit-io-operation-summary-title-case

Operation summaries should use Title Case.

$.paths[*][get,post,put,patch,delete].summary

warn

adafruit-io-api-key-security

Operations must declare the X-AIO-Key API key security scheme (except inbound webhooks).

$.paths[?([email protected]('^/webhooks'))][*][get,post,put,patch,delete]

hint

adafruit-io-snake-case-path-params

Path parameters use snake_case (feed_key, group_key, dashboard_id).

$.paths[*][get,post,put,patch,delete].parameters[?(@.in == "path")].name

hint

adafruit-io-pagination-headers

List endpoints should document the X-Pagination-* and Link headers.

$.paths[*][get].responses[200].headers

warn

adafruit-io-response-schema

2xx responses should reference a schema component.

$.paths[*][get,post,put,patch].responses[200,201].content[application/json].schema

Spectral Ruleset

extends: spectral:oas
formats:
  - oas3
documentationUrl: https://github.com/api-evangelist/adafruit-io
description: >
  Spectral ruleset enforcing the conventions used by the Adafruit IO REST API:
  username-scoped resource paths, X-AIO-Key API key auth, Title Case operation
  summaries, snake_case resource path segments, and HTTPS base URL.
rules:
  adafruit-io-https-only:
    description: All servers must use HTTPS.
    severity: error
    given: $.servers[*]
    then:
      field: url
      function: pattern
      functionOptions:
        match: '^https://'

  adafruit-io-base-path-v2:
    description: API base path must start with /api/v2.
    severity: warn
    given: $.servers[*]
    then:
      field: url
      function: pattern
      functionOptions:
        match: '/api/v2$|/api/v2/'

  adafruit-io-username-scoped:
    description: Every account-scoped path must be parameterized on {username}.
    severity: warn
    given: $.paths[?(@property != '/user' && @property !~ '^/webhooks')]~
    then:
      function: pattern
      functionOptions:
        match: '\{username\}'

  adafruit-io-operation-summary-title-case:
    description: Operation summaries should use Title Case.
    severity: warn
    given: '$.paths[*][get,post,put,patch,delete].summary'
    then:
      function: pattern
      functionOptions:
        match: '^[A-Z][A-Za-z0-9 /()\-]+$'

  adafruit-io-api-key-security:
    description: Operations must declare the X-AIO-Key API key security scheme (except inbound webhooks).
    severity: warn
    given: $.paths[?([email protected]('^/webhooks'))][*][get,post,put,patch,delete]
    then:
      field: security
      function: truthy

  adafruit-io-snake-case-path-params:
    description: Path parameters use snake_case (feed_key, group_key, dashboard_id).
    severity: hint
    given: '$.paths[*][get,post,put,patch,delete].parameters[?(@.in == "path")].name'
    then:
      function: pattern
      functionOptions:
        match: '^[a-z][a-z0-9_]*$'

  adafruit-io-pagination-headers:
    description: List endpoints should document the X-Pagination-* and Link headers.
    severity: hint
    given: '$.paths[*][get].responses[200].headers'
    then:
      function: truthy

  adafruit-io-response-schema:
    description: 2xx responses should reference a schema component.
    severity: warn
    given: '$.paths[*][get,post,put,patch].responses[200,201].content[application/json].schema'
    then:
      function: truthy