EPFL · API Governance Rules

EPFL API Rules

Spectral linting rules defining API design standards and conventions for EPFL.

5 Rules error 1 warn 3 info 1
View Rules File View on GitHub

Rule Categories

epfl

Rules

warn
epfl-info-contact
API info object should declare a contact for the EPFL API.
$.info
error
epfl-servers-https
EPFL API servers must use HTTPS.
$.servers[*].url
warn
epfl-collection-pagination
EPFL collection (list) endpoints should expose DRF limit/offset pagination parameters.
$.paths[?(@property.match(/\/$/))].get.parameters
warn
epfl-operation-id
Every operation should have an operationId.
$.paths[*][*]
info
epfl-paginated-list-envelope
Paginated list response schemas should follow the DRF envelope with count/next/previous/results.
$.components.schemas[?(@property.match(/^Paginated/))]

Spectral Ruleset

Raw ↑ 
extends: []
formats:
  - oas3
documentationUrl: https://actu.epfl.ch/api-docs/
rules:
  epfl-info-contact:
    description: API info object should declare a contact for the EPFL API.
    severity: warn
    given: $.info
    then:
      field: contact
      function: truthy

  epfl-servers-https:
    description: EPFL API servers must use HTTPS.
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: '^https://'

  epfl-collection-pagination:
    description: >-
      EPFL collection (list) endpoints should expose DRF limit/offset
      pagination parameters.
    severity: warn
    given: $.paths[?(@property.match(/\/$/))].get.parameters
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          contains:
            type: object
            properties:
              name:
                enum: [limit, offset]
            required: [name]

  epfl-operation-id:
    description: Every operation should have an operationId.
    severity: warn
    given: $.paths[*][*]
    then:
      field: operationId
      function: truthy

  epfl-paginated-list-envelope:
    description: >-
      Paginated list response schemas should follow the DRF envelope with
      count/next/previous/results.
    severity: info
    given: $.components.schemas[?(@property.match(/^Paginated/))]
    then:
      field: properties
      function: schema
      functionOptions:
        schema:
          type: object
          required: [count, next, previous, results]