API Meta Information

API Specifications MUST contain API metadata

API specifications MUST contain sufficient metadata to support API lifecycle management and governance.

The OpenAPI specification MUST provide the following information:

Field	Description
`#/info/title`	A unique and meaningful functional name identifying the API
`#/info/version`	The API specification version following semantic versioning rules
`#/info/description`	A clear and comprehensive description of the API

In addition, the following OpenAPI extension properties MUST be provided:

Field	Description
`#/info/x-api-id`	A unique and immutable identifier of the API
`#/info/x-audience`	The intended audience of the API

Example:

yaml

openapi: 3.0.1

info:
  title: User Management API
  description: API for managing user accounts and profiles.
  version: 1.2.0
  x-api-id: user-management-api-123456
  x-audience: company-internal

API Versioning MUST follow Semantic Versioning

The API version specified in:

shell

#/info/version

MUST follow Semantic Versioning 2.0 rules.

The API version format MUST be:

text

<MAJOR>.<MINOR>.<PATCH>

Example:

text

1.3.7

Version increment rules

MAJOR version

The MAJOR version MUST be increased when incompatible changes are introduced.

Examples:

Removing an existing endpoint
Removing or renaming request fields
Changing response structures in a breaking way
Changing API behavior that breaks existing consumers

Example:

text

1.0.0 -> 2.0.0

MINOR version

The MINOR version MUST be increased when new functionality is added in a backward-compatible manner.

Examples:

Adding a new endpoint
Adding optional request parameters
Adding new response fields without affecting existing clients

Example:

text

1.2.0 -> 1.3.0

PATCH version

The PATCH version MAY be increased for backward-compatible fixes or documentation changes.

Examples:

Fixing incorrect descriptions
Correcting examples
Fixing documentation errors

Example:

text

1.3.0 -> 1.3.1

API Version vs Software Version

API versioning describes changes in the external API contract.

It does NOT represent software release versions.

Examples:

An internal implementation change:

Refactoring code
Updating dependencies
Changing database implementation

does not require an API version change if the API contract remains unchanged.

Version restrictions

The following MUST NOT be used in API versions:

Pre-release identifiers

Example:

text

1.0.0-alpha

Build metadata

Example:

text

1.0.0+build123

Only the following format is allowed:

text

MAJOR.MINOR.PATCH

Example:

yaml

info:
  version: 1.3.7

API Identifier

Each API specification MUST provide a unique and immutable API identifier.

The identifier allows API lifecycle management, including:

Tracking API evolution
Maintaining API history
Linking different versions of the same API
Supporting automated compatibility checks

The identifier MUST remain unchanged throughout the API lifecycle.

Example:

yaml

info:
  x-api-id: user-management-api-123456

Recommended format:

yaml

x-api-id:
  type: string
  description: Unique and immutable identifier of the API.

Example:

yaml

info:
  x-api-id: d0184f38-b98d-11e7-9c56-68f728c1ba70

The API identifier identifies the API itself, while the API version identifies a specific evolution stage.

Example:

text

API ID:
user-management-api

Versions:
1.0.0
1.1.0
1.2.0
2.0.0

All versions belong to the same API lifecycle.

API Audience Classification

Each API MUST define its intended audience.

The audience classification helps determine:

API governance requirements
Documentation visibility
Security requirements
Change management rules
Review requirements

The audience MUST be defined in:

shell

#/info/x-audience

Allowed values:

yaml

x-audience:
  type: string

Supported values:

text

internal
company-internal
external-partner
external-public

Audience Definitions

Audience	Classification	Description
internal	System internal	Used only inside a component or subsystem owned by the same team
company-internal	Organization internal	Can be used across teams inside the organization but not exposed externally
external-partner	Partner API	Intended for authorized external partners
external-public	Public API	Available to external users over public networks

Audience Examples

Internal API

yaml

info:
  x-audience: internal

Example:

text

Service A -> Service B
within the same application

Company Internal API

yaml

info:
  x-audience: company-internal

Example:

text

Service A -> Service B
between different teams inside the organization

Partner API

yaml

info:
  x-audience: external-partner

Example:

text

Company system -> Business partner system

Public API

yaml

info:
  x-audience: external-public

Example:

text

Public Internet API

Audience Rules

Each API specification MUST define exactly one audience.
Multiple audience classifications MUST NOT be assigned to a single API.
If an API contains interfaces with different audiences, split them into separate API specifications.

Example:

Incorrect:

yaml

x-audience:
  - internal
  - external-public

Correct:

API A:

yaml

x-audience: internal

API B:

yaml

x-audience: external-public