[ADP-767] Re-use shared common HTTP headers

Overview

This ADP is one of the realization of ADP-761.

Guidance

• SHOULD reuse common HTTP headers in API definitions.

• To add new schemas, follow these steps:

  1. Copy the current models/headers-1.x.x.yaml file.
  2. Add the new schema to the copied file.
  3. Make sure to follow the semantic versioning guidelines as suggested in ADP-4.

• SHOULD use ADP-758: OpenAPI $ref for referencing shared components.

Referencing Common Headers

Use $ref to reference common headers in your API specification:

paths:
  /users:
    get:
      responses:
        '200':
          headers:
            X-Request-ID:
              $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/headers-1.0.0.yaml#/X-Request-ID'

Referencing Common Problem or Modify your own

openapi: 3.1.0
info:
  title: Example API with HTTP Problems
  version: 1.0.0
  description: An API demonstrating the use of HTTP Problem Details referencing an external schema.
paths:
  /items/{itemId}:
    parameters:
      - name: itemId
        in: path
        required: true
        schema:
          type: string
    get:
      summary: Retrieve an item
      operationId: getItem
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  description:
                    type: string
        '400':
          $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/problem-1.0.0.yaml#/400'
        '401':
          $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/problem-1.0.0.yaml#/401'
        '403':
          $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/problem-1.0.0.yaml#/403'
        '404':
          $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/problem-1.0.0.yaml#/404'
        'special-error':
          $ref: '#/components/schemas/SpecialError'
    put:
      summary: Update an item
      operationId: updateItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  description:
                    type: string
        '400':
          $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/problem-1.0.0.yaml#/400'
        '401':
          $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/problem-1.0.0.yaml#/401'
        '403':
          $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/problem-1.0.0.yaml#/403'
        '404':
          $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/problem-1.0.0.yaml#/404'
        '409':
          $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/problem-1.0.0.yaml#/409'
components:
  schemas:
    SpecialError:
      type: object
      allOf:
        - $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/problem-1.0.0.yaml'
        - type: object
          properties:
            status:
              type: integer
              example: 500
            title:
              type: string
              example: "Special Error"
            detail:
              type: string
              example: "This is a special customized error"
            extraType:
              type: string
              description: indicate the real problem type

Referencing Common Event with your own payload definition

openapi: 3.1.0
info:
  title: CloudEvents API
  version: 1.0.0
  description: API for handling CloudEvents with extended data

paths:
  /events:
    post:
      summary: Create a new CloudEvent
      requestBody:
        content:
          application/cloudevents+json:
            schema:
              $ref: '#/components/schemas/ExtendedCloudEvent'
      responses:
        '201':
          description: CloudEvent created successfully
          content:
            application/cloudevents+json:
              schema:
                $ref: '#/components/schemas/ExtendedCloudEvent'

    get:
      summary: Get a list of CloudEvents
      responses:
        '200':
          description: List of CloudEvents
          content:
            application/cloudevents+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExtendedCloudEvent'

  /events/{id}:
    get:
      summary: Get a CloudEvent by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Single CloudEvent
          content:
            application/cloudevents+json:
              schema:
                $ref: '#/components/schemas/ExtendedCloudEvent'
        '404':
          $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/problem-1.0.0.yaml#/404'

components:
  schemas:
    ExtendedCloudEvent:
      allOf:
        - $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/event-1.0.0.yaml#/CloudEvent'
        - type: object
          properties:
            data:
              type: object
              properties:
                customField1:
                  type: string
                  description: Custom field 1 for extended data
                customField2:
                  type: integer
                  description: Custom field 2 for extended data
              required:
                - customField1
                - customField2

Related ADPs

• ADP-758: OpenAPI $ref
• ADP-120: HTTP Headers
• ADP-121: Common HTTP Headers

References

• OpenAPI Specification
• RFC 7231: HTTP/1.1 Semantics and Content
• IETF HTTP Working Group