Michigan State University · API Governance Rules

Michigan State University API Rules

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

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

Rule Categories

msu

Rules

error
msu-info-title-present
API info object must declare a title.
$.info
error
msu-info-version-present
API info object must declare a version.
$.info
warn
msu-server-https
Catalog API servers should be served over HTTPS.
$.servers[*].url
warn
msu-operations-have-200
Every GET operation should define a 200 response (search/record endpoints return SearchResponse).
$.paths[*].get.responses
info
msu-search-response-status-ok
SearchResponse status enum should constrain to OK.
$.components.schemas.SearchResponse.properties.status
warn
msu-record-id-string
Record id should be typed as a string identifier.
$.components.schemas.Record.properties.id
info
msu-paths-kebab-or-flat
Catalog paths use flat lowercase segments (e.g. /search, /record, /web/search); avoid uppercase path segments.
$.paths[*]~

Spectral Ruleset

Raw ↑ 
---
# Spectral ruleset encoding patterns observed in the MSU Libraries VuFind
# Catalog REST API (OpenAPI 3.0.3, Library Catalog v11.0.4).
formats:
  - oas3
rules:
  msu-info-title-present:
    description: API info object must declare a title.
    severity: error
    given: $.info
    then:
      field: title
      function: truthy

  msu-info-version-present:
    description: API info object must declare a version.
    severity: error
    given: $.info
    then:
      field: version
      function: truthy

  msu-server-https:
    description: Catalog API servers should be served over HTTPS.
    severity: warn
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  msu-operations-have-200:
    description: Every GET operation should define a 200 response (search/record endpoints return SearchResponse).
    severity: warn
    given: $.paths[*].get.responses
    then:
      field: "200"
      function: truthy

  msu-search-response-status-ok:
    description: SearchResponse status enum should constrain to OK.
    severity: info
    given: $.components.schemas.SearchResponse.properties.status
    then:
      field: enum
      function: truthy

  msu-record-id-string:
    description: Record id should be typed as a string identifier.
    severity: warn
    given: $.components.schemas.Record.properties.id
    then:
      field: type
      function: truthy

  msu-paths-kebab-or-flat:
    description: Catalog paths use flat lowercase segments (e.g. /search, /record, /web/search); avoid uppercase path segments.
    severity: info
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^/[a-z0-9/_-]*$"