ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-769] OpenAPI Operation ​

This ADP outlines principles for designing OpenAPI operations (paths).

Guidance ​

Response Codes ​

  • Each operation MUST specify at least one 2xx successful response.
  • Operations SHOULD include appropriate error responses (4xx and 5xx).
  • Use standard HTTP status codes as defined in ADP-200: HTTP Status Codes.

Operation ID ​

API Audience ​

Parameters ​

  • Define all parameters using the parameters array at the operation level.
  • Use $ref to reference common parameters defined in the components section.

Request Body ​

  • For operations that accept a request body (e.g., POST, PUT, PATCH), define the requestBody object.
  • Specify the content type(s) supported (e.g., application/json).
  • Use $ref to reference request schemas defined in the components section.

Responses ​

  • Define responses for all possible status codes the operation may return.
  • Use $ref to reference response schemas defined in the components section.
  • Include examples where appropriate, following ADP-756: OpenAPI Provide Examples.

Security ​

  • Apply security requirements at the operation level if they differ from the global security scheme.
  • Reference security schemes defined in the components/securitySchemes section.

Description ​

  • SHOULD Provide a clear and concise description for each operation.
  • Include any important notes or caveats about the operation's behavior.

Deprecation/Sunset ​

  • Mark deprecated operations using the deprecated: true flag.
  • Include information about the deprecation in the operation's description, such as the reason for deprecation and suggested alternatives.
  • SHOULD reference pre-defined shared headers(See ADP-767: Shared common headers) for deprecation or components.headers(if you would not like to reference the external public header definitions yaml) to avoid redundant definitions.
  • SHOULD add sunset related descriptions since only adding Sunset header is not clear enough.

Rate Limiting ​

  • SHOULD include rate limiting information using x-rate-limit extension.
  • Follow ADP-753: OpenAPI x-rate-limit for implementation details.
  • SHOULD reference pre-defined shared headers(See ADP-767: Shared common headers) for rate limiting or components.headers(if you would not like to reference the external public header definitions yaml) to avoid redundant definitions.

Extensible Enums ​

  • For open-ended enumerations, SHOULD use x-extensible-enum instead of enum.
  • Follow ADP-768: Extensible Enums for implementation guidelines.

Example ​

Here's an example of a well-defined operation in OpenAPI 3.1.0:

yaml
components:
  headers:
    ETag:
      $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/headers-1.0.0.yaml#/ETag'
  parameters:
    CommonHeader:
      name: Common-Header
      in: header
      required: true
      schema:
        type: string
      description: This is an example header parameter
paths:
  /example:
    get:
      summary: Example endpoint
      parameters:
        - name: Example-Header
          in: header
          required: true
          schema:
            type: string
          description: This is an example header parameter
        - $ref: '#/components/parameters/CommonHeader'
  /users:
    post:
      operationId: createUser
      summary: Create a new user
      description: Creates a new user account with the provided information.
      tags:
        - users
      x-audience: public
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: Successful response
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
      x-rate-limit:
        rate: 100
        burst: 200
        unit: minute

References ​