Taddy API · API Governance Rules

Taddy API API Rules

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

8 Rules error 3 warn 4 info 1

View Rules File View on GitHub

Rule Categories

taddy

Rules

error

taddy-graphql-endpoint-must-be-post

Taddy GraphQL API only accepts POST requests

$.paths['/'].get

error

taddy-request-must-include-query

All GraphQL requests must include a query field

$.paths['/'].post.requestBody.content['application/json'].schema

warn

taddy-auth-headers-documented

API must document X-API-KEY and X-USER-ID authentication headers

$.components.securitySchemes

info

taddy-operations-have-examples

GraphQL operations should include request examples

$.paths['/'].post.requestBody.content['application/json'].examples

warn

taddy-response-includes-data-field

GraphQL responses should document the data wrapper

$.paths['/'].post.responses['200'].content['application/json'].schema.properties

warn

taddy-schemas-have-descriptions

All schema components should have descriptions

$.components.schemas[*]

error

taddy-uuid-fields-are-strings

UUID identifier fields must be typed as string

$.components.schemas[*].properties.uuid

warn

taddy-url-fields-use-uri-format

URL fields should use format uri

$.components.schemas[*].properties[*Url]

Spectral Ruleset

extends: spectral:oas
rules:
  taddy-graphql-endpoint-must-be-post:
    description: Taddy GraphQL API only accepts POST requests
    message: "GraphQL endpoints must use POST method"
    severity: error
    given: "$.paths['/'].get"
    then:
      function: undefined

  taddy-request-must-include-query:
    description: All GraphQL requests must include a query field
    message: "Request body must include a 'query' property"
    severity: error
    given: "$.paths['/'].post.requestBody.content['application/json'].schema"
    then:
      field: required
      function: truthy

  taddy-auth-headers-documented:
    description: API must document X-API-KEY and X-USER-ID authentication headers
    message: "API key authentication headers must be documented in securitySchemes"
    severity: warn
    given: "$.components.securitySchemes"
    then:
      function: truthy

  taddy-operations-have-examples:
    description: GraphQL operations should include request examples
    message: "Request body should include examples for key GraphQL queries"
    severity: info
    given: "$.paths['/'].post.requestBody.content['application/json'].examples"
    then:
      function: truthy

  taddy-response-includes-data-field:
    description: GraphQL responses should document the data wrapper
    message: "Response schema should include a 'data' property"
    severity: warn
    given: "$.paths['/'].post.responses['200'].content['application/json'].schema.properties"
    then:
      field: data
      function: truthy

  taddy-schemas-have-descriptions:
    description: All schema components should have descriptions
    message: "{{property}} is missing a description"
    severity: warn
    given: "$.components.schemas[*]"
    then:
      field: description
      function: truthy

  taddy-uuid-fields-are-strings:
    description: UUID identifier fields must be typed as string
    message: "UUID field '{{property}}' should be type: string"
    severity: error
    given: "$.components.schemas[*].properties.uuid"
    then:
      field: type
      function: pattern
      functionOptions:
        match: "^string$"

  taddy-url-fields-use-uri-format:
    description: URL fields should use format uri
    message: "URL field '{{property}}' should use format: uri"
    severity: warn
    given: "$.components.schemas[*].properties[*Url]"
    then:
      field: format
      function: pattern
      functionOptions:
        match: "^uri$"