Walk Score · API Governance Rules

Walk Score API Rules

Spectral linting rules defining API design standards and conventions for Walk Score.

7 Rules error 3 warn 4

View Rules File View on GitHub

Rule Categories

walk

Rules

error

walk-score-api-key-required

All Walk Score API requests must include the wsapikey parameter

$.paths[*][get].parameters[*]

error

walk-score-https-only

All Walk Score API server URLs must use HTTPS

$.servers[*].url

error

walk-score-operation-ids

All Walk Score API operations must have operationId

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

warn

walk-score-operation-summaries

All Walk Score API operations must have a summary in Title Case

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

warn

walk-score-lat-lon-params

Walk Score location endpoints should document lat and lon parameters

$.paths[*][get].parameters

warn

walk-score-json-format-support

Walk Score API endpoints should support JSON response format

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

warn

walk-score-status-codes

Walk Score API responses should include error status codes

$.paths[*][get].responses

Spectral Ruleset

extends: [[spectral:oas, recommended]]
rules:
  walk-score-api-key-required:
    description: All Walk Score API requests must include the wsapikey parameter
    message: "Walk Score API operations must require wsapikey authentication parameter"
    severity: error
    given: "$.paths[*][get].parameters[*]"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          if:
            properties:
              name:
                const: wsapikey
          then:
            properties:
              required:
                const: true

  walk-score-https-only:
    description: All Walk Score API server URLs must use HTTPS
    message: "Server URL must use HTTPS"
    severity: error
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  walk-score-operation-ids:
    description: All Walk Score API operations must have operationId
    message: "Operation must have an operationId"
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  walk-score-operation-summaries:
    description: All Walk Score API operations must have a summary in Title Case
    message: "Operation must have a summary"
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: summary
      function: truthy

  walk-score-lat-lon-params:
    description: Walk Score location endpoints should document lat and lon parameters
    message: "Location-based endpoints should include lat and lon parameters"
    severity: warn
    given: "$.paths[*][get].parameters"
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          contains:
            type: object
            properties:
              name:
                pattern: "^(lat|lon)$"

  walk-score-json-format-support:
    description: Walk Score API endpoints should support JSON response format
    message: "API should support JSON response format"
    severity: warn
    given: "$.paths[*][get].responses[200].content"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required:
            - "application/json"

  walk-score-status-codes:
    description: Walk Score API responses should include error status codes
    message: "Walk Score operations should document 400 error responses"
    severity: warn
    given: "$.paths[*][get].responses"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required:
            - "400"