ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-752] OpenAPI: API audience ​

Overview ​

  • API audience is for identifying the intended usage of an API and impacts API management. In ADP, many principles are designed based on the audience of the API. In OpenAPI, we utilize the extension field x-audience for specifying the API audience.

TIP

💡 Some API principle rules are based on the audience.

INFO

💡 Public documentation sites are generated based on the audience.

OpenAPI definition for x-audience ​

yaml
#/info/x-audience:
  type: string
  x-extensible-enum:
    - COMPONENT_INTERNAL
    - BUSINESS_UNIT_INTERNAL
    - COMPANY_INTERNAL
    - PARTNER_EXTERNAL
    - PUBLIC_EXTERNAL
  description: |
    Intended target audience of the API. Relevant for standards around
    quality of design and documentation, reviews, discoverability,
    changeability, and permission granting.

Guidance ​

  • MUST provide x-audience, which is one of the following, ordered by audience size:
ValueDescription
COMPONENT_INTERNALAPI usage is team-specific.
BUSINESS_UNIT_INTERNALAPI usage is within the same business unit.
COMPANY_INTERNALAPI audience targets different business units within the company.
PARTNER_EXTERNALAPI audience is specific partners.
PUBLIC_EXTERNALAPI audience is anyone with proper authentication.
  • SHOULD include the x-audience field at the API level (in the info object) to indicate the overall intended audience for the API.
  • MAY specify x-audience at the operation level to override the API-level audience for specific endpoints.

Example ​

yaml
openapi: 3.0.1
info:
  title: Sample API
  description: This is a sample API to demonstrate the usage of the x-audience field.
  version: 1.0.0
  x-audience: COMPANY_INTERNAL
  contact:
    name: API Support
    url: http://www.example.com/support
    email: support@example.com

paths:
  /items:
    get:
      summary: Retrieve a list of items
      operationId: getItems
      x-audience: PUBLIC_EXTERNAL
      responses:
        '200':
          description: A list of items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item'

  /internal/items:
    get:
      summary: Retrieve a list of internal items
      operationId: getInternalItems
      x-audience: COMPONENT_INTERNAL
      responses:
        '200':
          description: A list of internal items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalItem'

components:
  schemas:
    Item:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

    InternalItem:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        internalCode:
          type: string

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - ApiKeyAuth: []

Design Considerations ​

  • Generally speaking, an API designed for PUBLIC_EXTERNAL usage can be utilized by an internal team. However, there are scenarios where it's necessary to design APIs for different audiences. In such cases, it's crucial to design them carefully and assign unique operationId values for each API to distinguish their purposes and ensure proper usage. See SHOULD provide operationId.

Note: Exactly one audience per API specification is allowed at the API level. For this reason, a smaller audience group is intentionally included in the wider group and thus does not need to be declared additionally. If parts of your API have a different target audience, we recommend splitting API specifications along the target audience — even if this creates redundancies.

References ​

Design references ​