[ADP-57] API Spec discoverability

Guidance

• For discoverability and developer experience, SHOULD provide API specification location for all production APIs.
• MAY provide API spec location in your API server with the standard header Link upon the GET request to your root path of the API server.
• SHOULD use the service-desc or describedby relation type.
• SHOULD include content type information in the Link header to indicate the format of the API specification.
• MUST ensure the API specification URL is accessible with appropriate authentication if required.

TIP

describedby is registered in the IANA Link Relation Registry by POWDER via RFC 5988, and service-desc is registered by RFC 8631. Both of the semantics are suitable to describe the API spec location.

Implementation Details

Content Types

• When providing API specifications, the following content types SHOULD be supported:
  • application/openapi+json;version=3.0 - For OpenAPI 3.0 in JSON format
  • application/openapi+yaml;version=3.0 - For OpenAPI 3.0 in YAML format
  • application/vnd.oai.openapi+json;version=3.1 - For OpenAPI 3.1 in JSON format
  • application/vnd.oai.openapi+yaml;version=3.1 - For OpenAPI 3.1 in YAML format
  • application/vnd.aai.asyncapi+json;version=2.0 - For AsyncAPI 2.0 in JSON format
  • application/vnd.aai.asyncapi+yaml;version=2.0 - For AsyncAPI 2.0 in YAML format
  • application/vnd.aai.asyncapi+json;version=2.6 - For AsyncAPI 2.6 in JSON format
  • application/vnd.aai.asyncapi+yaml;version=2.6 - For AsyncAPI 2.6 in YAML format

Multiple Specifications

If multiple API specification formats are available, multiple Link headers MAY be provided:

Link: <https://api.example.com/openapi.json>; rel="service-desc"; type="application/openapi+json;version=3.0"
Link: <https://api.example.com/openapi.yaml>; rel="service-desc"; type="application/openapi+yaml;version=3.0"

Providing documentation site

To provide a specification documentation site, the following Link header MAY be provided:

Link: <https://api.example.com/docs>; rel="service-doc"

Design Thinking

This is inspired by a discussion here and this document here.

This design is to improve the API document discoverability. For sure, we could always provide the api document location before the user agent makes the first request; however, the agent who discovers the api server could utilize the Link header to find the api document location on its own. This approach implements a form of HATEOAS (Hypermedia as the Engine of Application State), allowing clients to dynamically discover API capabilities.

The use of standard Link headers provides a consistent, machine-readable way to discover API specifications across different services, enabling tooling to automatically find and use these specifications for testing, code generation, or documentation purposes.

Examples

Basic Example

Request:

GET / HTTP/1.1
Host: api.example.com

Response:

HTTP/1.1 200 OK
Link: <https://api.example.com/openapi.json>; rel="service-desc"; type="application/openapi+json;version=3.0"

Comprehensive Example

Request:

GET / HTTP/1.1
Host: api.example.com

Response:

HTTP/1.1 200 OK
Link: <https://api.example.com/openapi.json>; rel="service-desc"; type="application/openapi+json;version=3.0"
Link: <https://docs.example.com>; rel="service-doc"

References

• RFC 8288 - Web Linking
• RFC 5988 - Web Linking
• RFC 8631 - Link Relation Types for Web Services
• IANA Link Relation Registry
• Mapping OpenAPI to the CLI
• POWDER - Protocol for Web Description Resources
• OpenAPI Specification