Aarhus University · API Governance Rules

Aarhus University API Rules

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

7 Rules error 2 warn 2 info 2
View Rules File View on GitHub

Rule Categories

aarhus

Rules

warn
aarhus-info-title
API title should reference the Pure research information system.
$.info.title
error
aarhus-server-base
Servers should be hosted under the Aarhus Pure web-service base path.
$.servers[*].url
error
aarhus-api-key-security
An api-key security scheme must be defined (Pure endpoints require a valid API key).
$.components.securitySchemes
warn
aarhus-operation-tags
Every operation should carry at least one tag for discoverability.
$.paths[*][get,put,post,delete]
info
aarhus-list-pagination-params
Collection GET operations should expose size/offset paging used by the Pure API.
$.paths[?(@property.match(/s$/))].get.parameters
info
aarhus-uuid-path-params
Single-resource paths address records by uuid path parameter.
$.paths[?(@property.match(/{uuid}$/))]
hint
aarhus-no-empty-descriptions
Schemas should document themselves with a description.
$.components.schemas[*]

Spectral Ruleset

Raw ↑ 
---
# Spectral ruleset for the Aarhus University Pure research information REST API.
# Encodes patterns observed in the published OpenAPI 3.0.1 description
# (https://pure.au.dk/ws/api/openapi.json, Pure API 5.35.3-4).
formats:
  - oas3
rules:
  aarhus-info-title:
    description: API title should reference the Pure research information system.
    given: $.info.title
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: "Pure"

  aarhus-server-base:
    description: Servers should be hosted under the Aarhus Pure web-service base path.
    given: $.servers[*].url
    severity: error
    then:
      function: pattern
      functionOptions:
        match: "/ws/api"

  aarhus-api-key-security:
    description: An api-key security scheme must be defined (Pure endpoints require a valid API key).
    given: $.components.securitySchemes
    severity: error
    then:
      field: api-key
      function: truthy

  aarhus-operation-tags:
    description: Every operation should carry at least one tag for discoverability.
    given: $.paths[*][get,put,post,delete]
    severity: warn
    then:
      field: tags
      function: truthy

  aarhus-list-pagination-params:
    description: Collection GET operations should expose size/offset paging used by the Pure API.
    given: $.paths[?(@property.match(/s$/))].get.parameters
    severity: info
    then:
      function: truthy

  aarhus-uuid-path-params:
    description: Single-resource paths address records by uuid path parameter.
    given: $.paths[?(@property.match(/{uuid}$/))]
    severity: info
    then:
      function: truthy

  aarhus-no-empty-descriptions:
    description: Schemas should document themselves with a description.
    given: $.components.schemas[*]
    severity: hint
    then:
      field: description
      function: truthy