Taylor's University · API Governance Rules

Taylor's University API Rules

Spectral linting rules defining API design standards and conventions for Taylor's University.

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

Rule Categories

taylors

Rules

warn
taylors-info-contact
API info object should declare a contact for the Taylor's Library.
$.info
error
taylors-server-https
Servers must use HTTPS (Koha catalog is served over TLS).
$.servers[*].url
error
taylors-operation-id
Every operation should declare an operationId.
$.paths[*][get,post,put,patch,delete]
warn
taylors-operation-tags
Every operation should be tagged with its Koha resource collection.
$.paths[*][get,post,put,patch,delete]
warn
taylors-snake-case-properties
Koha REST API object properties use snake_case identifiers (e.g. patron_id, checkout_date, library_id).
$.components.schemas[*].properties.*~
info
taylors-id-suffix-integer
Internal resource identifiers ending in _id (patron_id, item_id, checkout_id, hold_id, biblio_id) are integers.
$.components.schemas[*].properties[?(@property.match(/^(patron|item|checkout|hold|biblio)_id$/))]
warn
taylors-auth-required
Patron and circulation collection endpoints must document a 401 Unauthorized response (anonymous access is rejected).
$.paths[*][get,post,put,patch,delete].responses

Spectral Ruleset

Raw ↑ 
extends: []
formats:
  - oas3
documentationUrl: https://librarycatalogue.taylors.edu.my/api/v1/
rules:
  taylors-info-contact:
    description: API info object should declare a contact for the Taylor's Library.
    severity: warn
    given: $.info
    then:
      field: contact
      function: truthy
  taylors-server-https:
    description: Servers must use HTTPS (Koha catalog is served over TLS).
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "^https://"
  taylors-operation-id:
    description: Every operation should declare an operationId.
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy
  taylors-operation-tags:
    description: Every operation should be tagged with its Koha resource collection.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: tags
      function: truthy
  taylors-snake-case-properties:
    description: >-
      Koha REST API object properties use snake_case identifiers
      (e.g. patron_id, checkout_date, library_id).
    severity: warn
    given: $.components.schemas[*].properties.*~
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-z0-9_]*$"
  taylors-id-suffix-integer:
    description: >-
      Internal resource identifiers ending in _id (patron_id, item_id,
      checkout_id, hold_id, biblio_id) are integers.
    severity: info
    given: $.components.schemas[*].properties[?(@property.match(/^(patron|item|checkout|hold|biblio)_id$/))]
    then:
      field: type
      function: pattern
      functionOptions:
        match: "integer"
  taylors-auth-required:
    description: >-
      Patron and circulation collection endpoints must document a 401
      Unauthorized response (anonymous access is rejected).
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      field: "401"
      function: truthy