University of Alberta · API Governance Rules

University of Alberta API Rules

Spectral linting rules defining API design standards and conventions for University of Alberta.

5 Rules error 2 warn 3
View Rules File View on GitHub

Rule Categories

ual

Rules

error
ual-borealis-https-server
Borealis API servers must use HTTPS.
$.servers[*].url
warn
ual-borealis-response-envelope
Borealis JSON responses wrap payloads in a status/data envelope.
$.components.schemas[?(@property.match(/Response$/))].properties
warn
ual-borealis-operation-id
Every operation should declare an operationId.
$.paths[*][get,post,put,delete]
error
ual-borealis-search-requires-q
The search operation must keep a required q query parameter.
$.paths['/search'].get.parameters[?(@.name=='q')]
warn
ual-borealis-apikey-header
The Dataverse API key uses the X-Dataverse-key header.
$.components.securitySchemes.DataverseApiKey

Spectral Ruleset

Raw ↑ 
extends: []
formats:
  - oas3
documentationUrl: https://borealisdata.ca/guides/en/latest/api/index.html
rules:
  ual-borealis-https-server:
    description: Borealis API servers must use HTTPS.
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: '^https://'

  ual-borealis-response-envelope:
    description: Borealis JSON responses wrap payloads in a status/data envelope.
    severity: warn
    given: $.components.schemas[?(@property.match(/Response$/))].properties
    then:
      - field: status
        function: truthy
      - field: data
        function: truthy

  ual-borealis-operation-id:
    description: Every operation should declare an operationId.
    severity: warn
    given: $.paths[*][get,post,put,delete]
    then:
      field: operationId
      function: truthy

  ual-borealis-search-requires-q:
    description: The search operation must keep a required q query parameter.
    severity: error
    given: $.paths['/search'].get.parameters[?(@.name=='q')]
    then:
      field: required
      function: truthy

  ual-borealis-apikey-header:
    description: The Dataverse API key uses the X-Dataverse-key header.
    severity: warn
    given: $.components.securitySchemes.DataverseApiKey
    then:
      - field: in
        function: pattern
        functionOptions:
          match: '^header$'
      - field: name
        function: pattern
        functionOptions:
          match: '^X-Dataverse-key$'