University of Pennsylvania · API Governance Rules

University of Pennsylvania API Rules

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

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

Rule Categories

upenn

Rules

error
upenn-info-title
API must declare a title.
$.info
warn
upenn-operation-description
Every operation should have a description (observed throughout the Penn Courses API).
$.paths[*][get,post,put,patch,delete]
warn
upenn-operation-tags
Operations should be tagged (e.g. Plan, Review, Alert, Degree, Base).
$.paths[*][get,post,put,patch,delete]
warn
upenn-path-kebab-or-snake
Path segments use lowercase letters, digits, dashes, underscores, or path params (observed convention, e.g. /api/review/course_plots).
$.paths[*]~
hint
upenn-course-code-param
Course code path params should be documented (e.g. course_code, full_code).
$.paths[*].*.parameters[?(@.in=='path')]
error
upenn-success-response
GET operations must define a 200 response.
$.paths[*].get.responses

Spectral Ruleset

Raw ↑ 
extends: [[spectral:oas, off]]
documentationUrl: https://penncoursereview.com/api/documentation/
formats:
  - oas3
rules:
  upenn-info-title:
    description: API must declare a title.
    severity: error
    given: $.info
    then:
      field: title
      function: truthy

  upenn-operation-description:
    description: Every operation should have a description (observed throughout the Penn Courses API).
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: description
      function: truthy

  upenn-operation-tags:
    description: Operations should be tagged (e.g. Plan, Review, Alert, Degree, Base).
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: tags
      function: truthy

  upenn-path-kebab-or-snake:
    description: Path segments use lowercase letters, digits, dashes, underscores, or path params (observed convention, e.g. /api/review/course_plots).
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: '^(/[a-z0-9_\-]+|/\{[a-zA-Z_]+\})+/?$'

  upenn-course-code-param:
    description: Course code path params should be documented (e.g. course_code, full_code).
    severity: hint
    given: $.paths[*].*.parameters[?(@.in=='path')]
    then:
      field: description
      function: truthy

  upenn-success-response:
    description: GET operations must define a 200 response.
    severity: error
    given: $.paths[*].get.responses
    then:
      field: '200'
      function: truthy