University of California, Davis · API Governance Rules

University of California, Davis API Rules

Spectral linting rules defining API design standards and conventions for University of California, Davis.

6 Rules error 2 warn 4
View Rules File View on GitHub

Rule Categories

peaks

Rules

error
peaks-info-title
API info object must carry a title.
$.info
warn
peaks-info-contact
PEAKS publishes an Application Support contact; require a contact object.
$.info
warn
peaks-apikey-security
PEAKS authenticates via an X-Auth-Token API key header; an apiKey security scheme should be defined.
$.components.securitySchemes
warn
peaks-paths-team-scoped
PEAKS resource paths are team-scoped and must include the {teamName} path parameter.
$.paths[?(@property.match(/^\/api\//))]~
warn
peaks-operation-tags
Every operation should be tagged to its resource group (access, keys, equipment, people, spaces, workstations, documents).
$.paths[*][get,post]
error
peaks-operation-responses
Every operation must declare responses.
$.paths[*][get,post]

Spectral Ruleset

Raw ↑ 
---
# Spectral ruleset encoding observed patterns in the UC Davis CAES PEAKS API.
# Derived from https://peaks.ucdavis.edu/swagger/v1/swagger.json (OpenAPI 3.0.1).
formats:
  - oas3
rules:
  peaks-info-title:
    description: API info object must carry a title.
    severity: error
    given: $.info
    then:
      field: title
      function: truthy

  peaks-info-contact:
    description: PEAKS publishes an Application Support contact; require a contact object.
    severity: warn
    given: $.info
    then:
      field: contact
      function: truthy

  peaks-apikey-security:
    description: PEAKS authenticates via an X-Auth-Token API key header; an apiKey security scheme should be defined.
    severity: warn
    given: $.components.securitySchemes
    then:
      field: ApiKey
      function: truthy

  peaks-paths-team-scoped:
    description: PEAKS resource paths are team-scoped and must include the {teamName} path parameter.
    severity: warn
    given: $.paths[?(@property.match(/^\/api\//))]~
    then:
      function: pattern
      functionOptions:
        match: "\\{teamName\\}"

  peaks-operation-tags:
    description: Every operation should be tagged to its resource group (access, keys, equipment, people, spaces, workstations, documents).
    severity: warn
    given: $.paths[*][get,post]
    then:
      field: tags
      function: truthy

  peaks-operation-responses:
    description: Every operation must declare responses.
    severity: error
    given: $.paths[*][get,post]
    then:
      field: responses
      function: truthy