University of Lausanne · API Governance Rules

University of Lausanne API Rules

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

5 Rules error 1 warn 3 info 1

View Rules File View on GitHub

Rule Categories

unil

Rules

warn

unil-info-contact

API info object should declare a contact pointing back to UNIL.

$.info

error

unil-https-servers

All servers must use HTTPS (UNIL APIs are HTTPS-only).

$.servers[*].url

warn

unil-operation-id

Every operation should declare an operationId.

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

info

unil-pagination-params

List/query operations should expose pagination parameters (SPICA uses page/per_page; DSpace uses page/size).

$.paths[*].get.parameters

warn

unil-json-responses

Successful responses should be served as application/json.

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

Spectral Ruleset

extends: [[spectral:oas, off]]
formats:
  - oas3
documentationUrl: https://spica.unil.ch/home/api
rules:
  unil-info-contact:
    description: API info object should declare a contact pointing back to UNIL.
    severity: warn
    given: $.info
    then:
      field: contact
      function: truthy
  unil-https-servers:
    description: All servers must use HTTPS (UNIL APIs are HTTPS-only).
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: '^https://'
  unil-operation-id:
    description: Every operation should declare an operationId.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy
  unil-pagination-params:
    description: >-
      List/query operations should expose pagination parameters (SPICA uses
      page/per_page; DSpace uses page/size).
    severity: info
    given: $.paths[*].get.parameters
    then:
      function: schema
      functionOptions:
        schema:
          type: array
  unil-json-responses:
    description: Successful responses should be served as application/json.
    severity: warn
    given: $.paths[*][get].responses.200.content
    then:
      function: defined