1.1.Goals and Non-Goals

The primary goal of this document is to facilitate the automated discoveryof a Publisher's public API endpoints, along with metadata that describes thepurpose and usage of each API, by specifying a well-known URI that returns anAPI catalog document. The API catalog document is primarily machine-readableto enable automated discovery and usage of APIs, and it may also include linksto human-readable documentation (see the example inAppendix A.1).¶

Non-goals: This document does not mandate paths for API endpoints, i.e., it does not mandate that my_example_api's endpoint should behttps://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).¶

1.2.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 asdescribed in BCP 14[RFC2119][RFC8174] when, and only when, theyappear in all capitals, as shown here.These words may also appear in this document inlower case as plain English words, absent their normative meanings.¶

The terms "content negotiation" and "status code" are from[HTTP].The term "well-known URI" is from[WELL-KNOWN].The term "link relation" is from[WEB-LINKING].¶

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.¶

3.1.Using Additional Link Relations

When used in an API catalog document, the "item"[RFC6573] link relation identifies a target resource that represents anAPI that is a member of the API catalog.¶

Other link relations may be utilised in an API catalog to conveymetadata descriptions for API links.¶

4.1.API Catalog Contents

The API catalogMUST include hyperlinks to APIendpoints. It isRECOMMENDED that the API catalog also includesuseful metadata, such as usage policies, API version information, links to theOpenAPI Specification[OAS] definitions for each API, etc. If the Publisher does not include that metadata directly in the API catalog document, theySHOULD make that metadata available at the API endpoint URIs they have listed (seeAppendix A.2 for an example).¶

4.2.API Catalog Formats

The PublisherMUST publish the API catalog document in the Linksetformatapplication/linkset+json (Section 4.2 of [RFC9264]). The LinksetSHOULD include a profile parameter (Section 5 of [RFC9264]) with a Profile URI[RFC7284] value of "https://www.rfc-editor.org/info/rfc9727"to indicate the Linkset is representing an API catalog document asdefined above.Appendix A includes example API catalog documents based on the Linkset format.¶

The PublisherMAY make additional formats available via content negotiation (Section 12 of [HTTP]) 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 atAppendix A.3. If a Publisher already lists theirAPIs in a format other than Linkset, but wishes to utilise the /.well-known/api-catalog URI, then:¶

• TheyMUST also implement a Linkset with, at minimum, hyperlinks toAPI endpoints; seeAppendix A.2.¶

• TheyMAY support content negotiation at the /.well-known/api-catalog URI to allow for the return of their existing format.¶

4.3.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 inAppendix A.4.¶

5.1.Accounting for APIs Distributed Across Multiple Domains

A Publisher ("example") may have their APIs hosted across multiple domains that they manage, e.g., atwww.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 isRECOMMENDED 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 theirinstances 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 latestAPI catalog is returned.¶

For example, if the Publisher's primary API portal ishttps://apis.example.com, thenhttps://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 forwww.example.net, which also hosts a selection of their APIs, then a request tohttps://www.example.net/.well-known/api-catalog should redirecttohttps://apis.example.com/.well-known/api-catalog.¶

If the Publisher is not the domain authority forwww.example.net, then the Publisher's API CatalogMAY include a link to the API catalog of the third-party that is the domain authority forwww.example.net. For example, the API catalog available athttps://apis.example.com/.well-known/api-catalog may list APIs hosted atapis.example.com and also link to the API catalog hosted athttps://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"  } ]}

5.2.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-partyuse. This scenario may incur additional security considerations as noted inSection 8.¶

5.3.Scalability Guidelines

In cases where a Publisher has a large number of APIs potentiallydeployed across multiple domains, two challenges may arise:¶

• Maintaining the catalog entries to ensure they are up to date andcorrecting 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 mainAPI catalog hosted at /.well-known/api-catalog to provide links tothese. For example, a Publisher may decide to group their APIsaccording to a business category (e.g., "gaming APIs", "anti-fraudAPIs", 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., atgaming.example.com,iot.example.net, etc.¶

Section 4.3 shows how the API catalog at/.well-known/api-catalog can use the api-catalog link relation topoint to other API catalogs.¶

The PublisherSHOULD consider caching and compression techniques to reduce the network overhead of large API catalogs.¶

5.4.Monitoring and Maintenance

Publishers areRECOMMENDED to follow operational best practice whenhosting API catalog(s), including, but not limited to:¶

• Availability. The Publisher should monitor availability of the APIcatalog 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 APIcatalog can demand high transactions per second and low-latencyresponse, the retrieval of the API catalog itself to discover thoseAPIs is less likely to incur strict performance demands. That said,the Publisher should monitor the response time to fulfil a requestfor the API catalog and determine any necessary improvements (aswith any other Web resource the Publisher serves). For large APIcatalogs, the Publisher should consider the techniques described inSection 5.3.¶

• Usage. Since the goal of the api-catalog well-known URI is tofacilitate discovery of APIs, the Publisher may wish to correlaterequests to the /.well-known/api-catalog URI with subsequent requeststo the API URIs listed in the catalog.¶

• Current data. The Publisher should include the removal of stale APIentries from the API catalog as part of their API release lifecycle.The PublisherMAY decide to include metadata regarding legacy APIversions or deprecated APIs to help users of those APIs discoverup-to-date alternatives.¶

• Correct metadata. The Publisher should include human and/orautomated checks for syntax errors in the API catalog. Automatedchecks include format validation (e.g., to ensure valid JSON syntax)and linting to enforce business rules, such as removing duplicateentries and ensuring descriptions are correctly named with validvalues. A proofread of the API catalog as part of the API releaselifecycle isRECOMMENDED to detect any errors in business grammar(for example, an API entry that is described with valid syntax, buthas been allocated an incorrect or outdated description.)¶

• Security best practice. SeeSection 8.¶

5.5.Integration with Existing API Management Frameworks

A Publisher may already utilise an API management framework toproduce their API portfolio. These frameworks typically include thepublication of API endpoint URIs, deprecation and redirection oflegacy API versions, API usage policies and documentation, etc.The api-catalog well-known URI and API catalog document are intendedto complement API management frameworks by facilitating the discoveryof the framework's outputs -- API endpoints, usage policies, anddocumentation -- and are not intended to replace any existingAPI discovery mechanisms the framework has implemented.¶

Providers of such frameworks may include the production of an APIcatalog and the publication of the /.well-known/api-catalog URI as afinal pre-release (or post-release) step in the release managementworkflow. 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 includedin the API catalog. This metadata is likely to already exist in theframework.¶

• Determine which metadata to include in the API catalog followingthe requirements set out inSection 4.1 and theconsiderations set out inSection 5.¶

• Map the chosen metadata to the format(s) described inSection 4.2. The structure suggested inAppendix A.2 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 inSection 4.1; in which case, the structuresuggested inAppendix A can be utilised andadapted (ensuring compliance to[RFC9264]) to reflect the natureof the chosen metadata.¶

• Publish the /.well-known/api-catalog URI following the guidance setout inSection 2.¶

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 theAPI catalog following any changes in API hyperlinks or publishedmetadata. This could include placing triggers on certain metadatafields, so that as they are updated in pre-production on the APIframework, the updates are pushed to a pre-production copy of the APIcatalog to be pushed live when the release is published by theframework.¶

6.1.Path Suffix

The api-catalog URISHALL be appended to the /.well-known/path-prefix for "well-known locations".¶

6.2.Formats and Associated Media Types

A /.well-known/api-catalog locationMUST support the Linkset[RFC9264] format of application/linkset+json andMAYalso support the other formats via content negotiation.¶

7.1.The api-catalog Well-Known URI

This specification registers the "api-catalog" well-known URI in the "Well-Known URIs" registry as defined by[WELL-KNOWN].¶

URI Suffix:

api-catalog¶

Reference:

RFC 9727¶

Status:

permanent¶

Change Controller:

IETF¶

7.2.The api-catalog Link Relation

This specification registers the "api-catalog" link relation in the "Link Relation Types" registry by following the procedures perSection 2.1.1.1 of [WEB-LINKING].¶

Relation Name:

api-catalog¶

Description:

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

Reference:

RFC 9727¶

7.3.The api-catalog Profile URI

This specification registers "https://www.rfc-editor.org/info/rfc9727" in the "Profile URIs" registry according to[RFC7284].¶

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¶

A.1.Using Linkset with Link Relations Defined in RFC 8631

This example uses the Linkset format[RFC9264] and the followinglink relations defined in[RFC8631]:¶

"service-desc":

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

"service-doc":

Used to link to API documentation that is primarilyintended for human consumption (an example of human-readabledocumentation is the IETFInternet-Draft submission APIinstructions).¶

"service-meta":

Used to link to additional metadata about the APIand 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.1Host: example.comAccept: application/linkset+json

Server response:¶

HTTP/1.1 200 OKDate: Mon, 01 Jun 2023 00:00:01 GMTServer: Apache-Coyote/1.1Content-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"    }   ]  } ]}

A.2.Using Linkset with Bookmarks

This example also uses the Linkset format[RFC9264] 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"[RFC9264] 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.1Host: example.comAccept: application/linkset+json

Server response:¶

HTTP/1.1 200 OKDate: Mon, 01 Jun 2023 00:00:01 GMTServer: Apache-Coyote/1.1Content-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"}     ]   } ]}

A.3.Other API Catalog Formats

A non-exhaustive list of other API catalog document formats includes:¶

• An APIs.json document[APIsjson].¶

• A RESTDesc semantic description for hypermedia APIs[RESTdesc].¶

• A Hypertext Application Language document[HAL].¶

• An extension to the Schema.org WebAPI type[WebAPIext].¶

A.4.Nesting API Catalog Links

In this example, a request to the /.well-known/api-catalog URIreturns an array of links of relation type "api-catalog". This can beuseful to Publishers with a large number of APIs who wish to groupthem in smaller catalogs (as described inSection 5.3).¶

Client request:¶

GET .well-known/api-catalog HTTP/1.1Host: example.comAccept: application/linkset+json

Server response:¶

HTTP/1.1 200 OKDate: Mon, 01 Jun 2023 00:00:01 GMTServer: Apache-Coyote/1.1Content-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"        }      ]    }  ]}