Vodafone

kevin.smith@vodafone.com https://www.vodafone.com

WIT httpapi API This document defines the "api-catalog" well-known URI and link relation. It is intended to facilitate automated discovery and usage of published Application Programming Interfaces (APIs). A request to the api-catalog resource will return a document providing information about, and links to, the Publisher's APIs.

Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at .

Copyright Notice Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents () in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.

Table of Contents

• .  Introduction
  • .  Goals and Non-Goals
  • .  Notational Conventions
• .  Using the "api-catalog" Well-Known URI
• .  The api-catalog Link Relation
  • .  Using Additional Link Relations
• .  The API Catalog Document
  • .  API Catalog Contents
  • .  API Catalog Formats
  • .  Nesting API Catalog Links
• .  Operational Considerations
  • .  Accounting for APIs Distributed Across Multiple Domains
  • .  Internal Use of api-catalog for Private APIs
  • .  Scalability Guidelines
  • .  Monitoring and Maintenance
  • .  Integration with Existing API Management Frameworks
• .  Conformance to RFC 8615
  • .  Path Suffix
  • .  Formats and Associated Media Types
• .  IANA Considerations
  • .  The api-catalog Well-Known URI
  • .  The api-catalog Link Relation
  • .  The api-catalog Profile URI
• .  Security Considerations
• .  References
  • .  Normative References
  • .  Informative References
• .  Example API Catalog Documents
  • .  Using Linkset with Link Relations Defined in RFC 8631
  • .  Using Linkset with Bookmarks
  • .  Other API Catalog Formats
  • .  Nesting API Catalog Links
• Acknowledgements
• Author's Address

Introduction An application may publish APIs to encourage requests for interaction from external parties. Such APIs must be discovered before they may be used, i.e., the external party needs to know what APIs a given Publisher exposes, their purpose, any policies for usage, and the endpoint to interact with each API. To facilitate automated discovery of this information and automated usage of the APIs, this document proposes:

• a well-known URI , "api-catalog", that is encoded as a URI reference to an API catalog document describing a Publisher's API endpoints.
• a link relation , "api-catalog", of which the target resource is the Publisher's API catalog document.

Goals and Non-Goals The primary goal of this document is to facilitate the automated discovery of a Publisher's public API endpoints, along with metadata that describes the purpose and usage of each API, by specifying a well-known URI that returns an API catalog document. The API catalog document is primarily machine-readable to enable automated discovery and usage of APIs, and it may also include links to human-readable documentation (see the example in ). Non-goals: This document does not mandate paths for API endpoints, i.e., it does not mandate that my_example_api's endpoint should be https://www.example.com/.well-known/api-catalog/my_example_api, nor even to be hosted at www.example.com (although it is not forbidden to do so).

Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. These words may also appear in this document in lower case as plain English words, absent their normative meanings. The terms "content negotiation" and "status code" are from . The term "well-known URI" is from . The term "link relation" is from . The term "Publisher" refers to an organisation, company, or individual that publishes one or more APIs for use by external third parties. A fictional Publisher named "example" is used throughout this document. The examples use the Fully Qualified Domain Names (FQDNs) "www.example.com", "developer.example.com", "apis.example.com", "apis.example.net", "gaming.example.com", and "iot.example.net", where the .com and .net Top-Level Domains (TLDs) and various subdomains are simply used to illustrate that the "example" Publisher may have their API portfolio distributed across various domains for which they are the authority. Scenarios where the Publisher "example" is not the authority for a given .example. domain are made explicit in the text. In this document, "API" refers to the specification resources required for an external party (or in the case of "private" APIs, an internal party) to implement software that uses the Publisher's API. The specification recommends the use of TLS. Hence, "HTTPS" and "https://" are used throughout.

Using the "api-catalog" Well-Known URI The api-catalog well-known URI is intended for HTTPS servers that publish APIs.

• The API catalog MUST be named "api-catalog" in a well-known location as described by .
• The location of the API catalog document is decided by the Publisher. The /.well-known/api-catalog URI provides a convenient reference to that location.

A Publisher supporting this URI:

• SHALL resolve an HTTPS GET request to /.well-known/api-catalog and return an API catalog document (as described in ).
• SHALL resolve an HTTPS HEAD request to /.well-known/api-catalog with a response including a Link header with the relation(s) defined in .

The api-catalog Link Relation This document introduces a new link relation , "api-catalog". This identifies a target resource that represents a list of APIs available from the Publisher of the link context. The target resource URI may be /.well-known/api-catalog or any other URI chosen by the Publisher. For example, the Publisher "example" could include the api-catalog link relation in the HTTP header and/or content payload when responding to a request to https://www.example.com: HTTP/1.1 200 OK Content-Type: text/html; charset=UTF-8 Location: /index.html Link: </my_api_catalog.json>; rel=api-catalog Content-Length: 356 <!DOCTYPE HTML> <html> <head> <title>Welcome to Example Publisher</title> </head> <body> <p> <a href="my_api_catalog.json" rel="api-catalog"> Example Publisher's APIs </a> </p> <p>(remainder of content)</p> </body> </html>

Using Additional Link Relations When used in an API catalog document, the "item" link relation identifies a target resource that represents an API that is a member of the API catalog. Other link relations may be utilised in an API catalog to convey metadata descriptions for API links.

The API Catalog Document The API catalog is a document listing a Publisher's APIs. The Publisher may host the API catalog document at any URI(s) they choose. For example, the API catalog document URI of https://www.example.com/my_api_catalog.json can be requested directly or via a request to https://www.example.com/.well-known/api-catalog, which the Publisher will resolve to https://www.example.com/my_api_catalog.

API Catalog Contents The API catalog MUST include hyperlinks to API endpoints. It is RECOMMENDED that the API catalog also includes useful metadata, such as usage policies, API version information, links to the OpenAPI Specification definitions for each API, etc. If the Publisher does not include that metadata directly in the API catalog document, they SHOULD make that metadata available at the API endpoint URIs they have listed (see for an example).

API Catalog Formats The Publisher MUST publish the API catalog document in the Linkset format application/linkset+json (). The Linkset SHOULD include a profile parameter () with a Profile URI value of "https://www.rfc-editor.org/info/rfc9727" to indicate the Linkset is representing an API catalog document as defined above. includes example API catalog documents based on the Linkset format. The Publisher MAY make additional formats available via content negotiation () to their /.well-known/api-catalog location. A non-exhaustive list of such formats that support the automated discovery and machine (and human) usage of a Publisher's APIs is listed at . If a Publisher already lists their APIs in a format other than Linkset, but wishes to utilise the /.well-known/api-catalog URI, then:

• They MUST also implement a Linkset with, at minimum, hyperlinks to API endpoints; see .
• They MAY support content negotiation at the /.well-known/api-catalog URI to allow for the return of their existing format.

Nesting API Catalog Links An API catalog may itself contain links to other API catalogs by using the "api-catalog" relation type for each link. An example of this is given in .

Operational Considerations

Accounting for APIs Distributed Across Multiple Domains A Publisher ("example") may have their APIs hosted across multiple domains that they manage, e.g., at www.example.com, developer.example.com, apis.example.com, apis.example.net, etc. They may also use a third-party API hosting provider that hosts APIs on a distinct domain. To account for this scenario, it is RECOMMENDED that:

• The Publisher also publish the api-catalog well-known URI at each of their API domains, e.g., https://apis.example.com/.well-known/api-catalog, https://developer.example.net/.well-known/api-catalog, etc.
• An HTTPS GET request to any of these URIs returns the same result, namely, the API catalog document.
• The Publisher choose one of their instances of /.well-known/api-catalog as a canonical reference to the location of the latest API catalog since the physical location of the API catalog document is decided by the Publisher and may change. The Publisher's other instances of /.well-known/api-catalog should redirect to this canonical instance of /.well-known/api-catalog to ensure the latest API catalog is returned.

For example, if the Publisher's primary API portal is https://apis.example.com, then https://apis.example.com/.well-known/api-catalog should resolve to the location of the Publisher's latest API catalog document. If the Publisher is also the domain authority for www.example.net, which also hosts a selection of their APIs, then a request to https://www.example.net/.well-known/api-catalog should redirect to https://apis.example.com/.well-known/api-catalog. If the Publisher is not the domain authority for www.example.net, then the Publisher's API Catalog MAY include a link to the API catalog of the third-party that is the domain authority for www.example.net. For example, the API catalog available at https://apis.example.com/.well-known/api-catalog may list APIs hosted at apis.example.com and also link to the API catalog hosted at https://www.example.net/.well-known/api-catalog using the "api-catalog" link relation: { "linkset": [ { "anchor": "https://www.example.com/.well-known/api-catalog", "item": [ { "href": "https://developer.example.com/apis/foo_api" }, { "href": "https://developer.example.com/apis/bar_api" }, { "href": "https://developer.example.com/apis/cantona_api" } ], "api-catalog": "https://www.example.net/.well-known/api-catalog" } ] }

Internal Use of api-catalog for Private APIs A Publisher may wish to use the api-catalog well-known URI on their internal network to signpost authorised users (e.g., company employees) towards internal/private APIs not intended for third-party use. This scenario may incur additional security considerations as noted in .

Scalability Guidelines In cases where a Publisher has a large number of APIs potentially deployed across multiple domains, two challenges may arise:

• Maintaining the catalog entries to ensure they are up to date and correcting any errors.
• Restricting the catalog size to help reduce network and client-processing overheads.

In both cases, a Publisher may benefit from grouping their APIs, providing an API catalog document for each group and using the main API catalog hosted at /.well-known/api-catalog to provide links to these. For example, a Publisher may decide to group their APIs according to a business category (e.g., "gaming APIs", "anti-fraud APIs", etc.), a technology category (e.g., "IOT", "networks", "AI", etc.), or any other criterion. This grouping may be implicit where the Publisher has already published their APIs across multiple domains, e.g., at gaming.example.com, iot.example.net, etc. shows how the API catalog at /.well-known/api-catalog can use the api-catalog link relation to point to other API catalogs. The Publisher SHOULD consider caching and compression techniques to reduce the network overhead of large API catalogs.

Monitoring and Maintenance Publishers are RECOMMENDED to follow operational best practice when hosting API catalog(s), including, but not limited to:

• Availability. The Publisher should monitor availability of the API catalog and consider alternate means to resolve requests to /.well-known/api-catalog during planned downtime of hosts.
• Performance. Although the performance of APIs listed in an API catalog can demand high transactions per second and low-latency response, the retrieval of the API catalog itself to discover those APIs is less likely to incur strict performance demands. That said, the Publisher should monitor the response time to fulfil a request for the API catalog and determine any necessary improvements (as with any other Web resource the Publisher serves). For large API catalogs, the Publisher should consider the techniques described in .
• Usage. Since the goal of the api-catalog well-known URI is to facilitate discovery of APIs, the Publisher may wish to correlate requests to the /.well-known/api-catalog URI with subsequent requests to the API URIs listed in the catalog.
• Current data. The Publisher should include the removal of stale API entries from the API catalog as part of their API release lifecycle. The Publisher MAY decide to include metadata regarding legacy API versions or deprecated APIs to help users of those APIs discover up-to-date alternatives.
• Correct metadata. The Publisher should include human and/or automated checks for syntax errors in the API catalog. Automated checks include format validation (e.g., to ensure valid JSON syntax) and linting to enforce business rules, such as removing duplicate entries and ensuring descriptions are correctly named with valid values. A proofread of the API catalog as part of the API release lifecycle is RECOMMENDED to detect any errors in business grammar (for example, an API entry that is described with valid syntax, but has been allocated an incorrect or outdated description.)
• Security best practice. See .

Integration with Existing API Management Frameworks A Publisher may already utilise an API management framework to produce their API portfolio. These frameworks typically include the publication of API endpoint URIs, deprecation and redirection of legacy API versions, API usage policies and documentation, etc. The api-catalog well-known URI and API catalog document are intended to complement API management frameworks by facilitating the discovery of the framework's outputs -- API endpoints, usage policies, and documentation -- and are not intended to replace any existing API discovery mechanisms the framework has implemented. Providers of such frameworks may include the production of an API catalog and the publication of the /.well-known/api-catalog URI as a final pre-release (or post-release) step in the release management workflow. The following steps are recommended. If the /.well-known/api-catalog URI has not been published previously, the framework provider should:

• Collate and check the metadata for each API that will be included in the API catalog. This metadata is likely to already exist in the framework.
• Determine which metadata to include in the API catalog following the requirements set out in and the considerations set out in .
• Map the chosen metadata to the format(s) described in . The structure suggested in may be followed where only the hyperlinks to APIs are to be included in the API catalog. Where possible, the API catalog should include further metadata per the guidance in ; in which case, the structure suggested in can be utilised and adapted (ensuring compliance to ) to reflect the nature of the chosen metadata.
• Publish the /.well-known/api-catalog URI following the guidance set out in .

If the /.well-known/api-catalog URI has previously been published, the framework provider should:

• Include a step in the release management lifecycle to refresh the API catalog following any changes in API hyperlinks or published metadata. This could include placing triggers on certain metadata fields, so that as they are updated in pre-production on the API framework, the updates are pushed to a pre-production copy of the API catalog to be pushed live when the release is published by the framework.

Conformance to RFC 8615 The requirements in for defining Well-Known URIs are met as described in the following subsections.

Path Suffix The api-catalog URI SHALL be appended to the /.well-known/ path-prefix for "well-known locations".

Formats and Associated Media Types A /.well-known/api-catalog location MUST support the Linkset format of application/linkset+json and MAY also support the other formats via content negotiation.

IANA Considerations

The api-catalog Well-Known URI This specification registers the "api-catalog" well-known URI in the "Well-Known URIs" registry as defined by .

URI Suffix:

api-catalog

Reference:

RFC 9727

Status:

permanent

Change Controller:

IETF

The api-catalog Link Relation This specification registers the "api-catalog" link relation in the "Link Relation Types" registry by following the procedures per .

Relation Name:

api-catalog

Description:

Refers to a list of APIs available from the Publisher of the link context.

Reference:

RFC 9727

The api-catalog Profile URI This specification registers "https://www.rfc-editor.org/info/rfc9727" in the "Profile URIs" registry according to .

Profile URI:

https://www.rfc-editor.org/info/rfc9727

Common Name:

API catalog

Description:

A Profile URI to request or signal a Linkset representing an API catalog.

Reference:

RFC 9727

Security Considerations For all scenarios:

• TLS SHOULD be used, i.e., make /.well-known/api-catalog available exclusively over HTTPS, to ensure no tampering of the API catalog.
• The Publisher SHOULD take into account the security considerations from .
• The Publisher SHOULD perform a security and privacy review of the API catalog prior to deployment to ensure it does not leak personal, business, or other sensitive metadata, nor expose any vulnerability related to the APIs listed.
• The Publisher SHOULD enforce read-only privileges for external requests to .well-known/api-catalog and for internal systems and roles that monitor the .well-known/api-catalog URI. Write privileges SHOULD only be granted to roles that perform updates to the API catalog and/or the forwarding rewrite rules for the .well-known/api-catalog URI.
• As with any Web offering, it is RECOMMENDED to apply rate-limiting measures to help mitigate abuse and prevent denial-of-service attacks on the API catalog endpoint.

For the public-facing APIs scenario, security teams SHOULD additionally audit the API catalog to ensure no APIs intended solely for internal use have been mistakenly included. For example, a catalog hosted on https://developer.example.com should not expose unnecessary metadata about any internal domains (e.g., https://internal.example.com). For the internal/private APIs scenario, the Publisher SHOULD take steps to ensure that appropriate controls, such as Cross-Origin Resource Sharing (CORS) policies and access control lists, are in place to ensure only authorised roles and systems may access an internal api-catalog well-known URI. A comprehensive API catalog that is regularly audited may assist the Publisher in decommissioning "zombie" APIs, i.e., legacy/obsolete APIs that should no longer be available. Such APIs represent a security vulnerability as they are unlikely to be supported, monitored, patched, or updated. Note the registration of domain names and associated policies is out of scope of this document.

References Normative References The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 5988 standardized a means of indicating the relationships between resources on the Web. This specification defines a pair of reciprocal link relation types that may be used to express the relationship between a collection and its members. This document is not an Internet Standards Track specification; it is published for informational purposes. This document defines a registry for profile URIs to be used in specifications standardizing profiles. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This specification defines two formats and associated media types for representing sets of links as standalone documents. One format is based on JSON, and the other is aligned with the format for representing links in the HTTP "Link" header field. This specification also introduces a link relation type to support the discovery of sets of links. This specification defines a model for the relationships between resources on the Web ("links") and the type of those relationships ("link relation types"). It also defines the serialisation of such links in HTTP headers with the Link header field. This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. In doing so, it obsoletes RFC 5785 and updates the URI schemes defined in RFC 7230 to reserve that space. It also updates RFC 7595 to track URI schemes that support well-known URIs in their registry. Informative References Latest version available at . Stateless This document proposes a media type for representing resources and their relations with hyperlinks. Work in Progress Latest version available at . Many resources provided on the Web are part of sets of resources that are provided in a context that is managed by one particular service provider. Often, these sets of resources are referred to as "Web services" or "Web APIs". This specification defines link relations that represent relationships from Web services or APIs to resources that provide documentation, descriptions, metadata, or status information for these resources. Documentation is primarily intended for human consumers, whereas descriptions are primarily intended for automated consumers. Metadata provides information about a service's context. This specification also defines a link relation to identify status resources that are used to represent information about service status. Draft Community Group Report

Example API Catalog Documents This section is informative and provides and example of an API catalog document using the Linkset format.

Using Linkset with Link Relations Defined in RFC 8631 This example uses the Linkset format and the following link relations defined in :

"service-desc":

Used to link to a description of the API that is primarily intended for machine consumption (for example, the specification, YAML, or JSON file).

"service-doc":

Used to link to API documentation that is primarily intended for human consumption (an example of human-readable documentation is the IETF Internet-Draft submission API instructions).

"service-meta":

Used to link to additional metadata about the API and is primarily intended for machine consumption.

"status":

Used to link to the API status (e.g., API "health" indication) for machine and/or human consumption.

Client request: GET .well-known/api-catalog HTTP/1.1 Host: example.com Accept: application/linkset+json Server response: HTTP/1.1 200 OK Date: Mon, 01 Jun 2023 00:00:01 GMT Server: Apache-Coyote/1.1 Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727" { "linkset": [ { "anchor": "https://developer.example.com/apis/foo_api", "service-desc": [ { "href": "https://developer.example.com/apis/foo_api/spec", "type": "application/yaml" } ], "status": [ { "href": "https://developer.example.com/apis/foo_api/status", "type": "application/json" } ], "service-doc": [ { "href": "https://developer.example.com/apis/foo_api/doc", "type": "text/html" } ], "service-meta": [ { "href": "https://developer.example.com/apis/foo_api/policies", "type": "text/xml" } ] }, { "anchor": "https://developer.example.com/apis/bar_api", "service-desc": [ { "href": "https://developer.example.com/apis/bar_api/spec", "type": "application/yaml" } ], "status": [ { "href": "https://developer.example.com/apis/bar_api/status", "type": "application/json" } ], "service-doc": [ { "href": "https://developer.example.com/apis/bar_api/doc", "type": "text/plain" } ] }, { "anchor": "https://apis.example.net/apis/cantona_api", "service-desc": [ { "href": "https://apis.example.net/apis/cantona_api/spec", "type": "text/n3" } ], "service-doc": [ { "href": "https://apis.example.net/apis/cantona_api/doc", "type": "text/html" } ] } ] }

Using Linkset with Bookmarks This example also uses the Linkset format and lists the API endpoints in an array of bookmarks. Each link shares the same context anchor (the well-known URI of the API catalog) and "item" link relation (to indicate they are an item in the catalog). The intent is that by following a bookmark link, a machine client can discover the purpose and usage policy for each API; hence, the document targeted by the bookmark link should support this. Client request: GET .well-known/api-catalog HTTP/1.1 Host: example.com Accept: application/linkset+json Server response: HTTP/1.1 200 OK Date: Mon, 01 Jun 2023 00:00:01 GMT Server: Apache-Coyote/1.1 Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727" { "linkset": [ { "anchor": "https://www.example.com/.well-known/api-catalog", "item": [ {"href": "https://developer.example.com/apis/foo_api"}, {"href": "https://developer.example.com/apis/bar_api"}, {"href": "https://developer.example.com/apis/cantona_api"} ] } ] }

Other API Catalog Formats A non-exhaustive list of other API catalog document formats includes:

• An APIs.json document .
• A RESTDesc semantic description for hypermedia APIs .
• A Hypertext Application Language document .
• An extension to the Schema.org WebAPI type .

Nesting API Catalog Links In this example, a request to the /.well-known/api-catalog URI returns an array of links of relation type "api-catalog". This can be useful to Publishers with a large number of APIs who wish to group them in smaller catalogs (as described in ). Client request: GET .well-known/api-catalog HTTP/1.1 Host: example.com Accept: application/linkset+json Server response: HTTP/1.1 200 OK Date: Mon, 01 Jun 2023 00:00:01 GMT Server: Apache-Coyote/1.1 Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727" { "linkset": [ { "anchor": "https://www.example.com/.well-known/api-catalog", "api-catalog": [ { "href": "https://apis.example.com/iot/api-catalog" }, { "href": "https://ecommerce.example.com/api-catalog" }, { "href": "https://developer.example.com/gaming/api-catalog" } ] } ] }

Acknowledgements Thanks to , , , , , , , , , , , , , , , , , , , , and for their reviews, suggestions, and support.

Author's Address Vodafone

kevin.smith@vodafone.com https://www.vodafone.com