RFC 9727

api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs

📅 published June 2025, from ietf

okay bestie, here are the deets 💅

  • Stream: Internet Engineering Task Force (IETF) 🌸
  • Author: K. Smith, Vodafone 🎀
  • Category: Standards Track 👑
  • Date: June 2025 📅
  • ISSN: 2070-1721 ✨
  • Obsoletes / Updates: the title block doesn't list anything this one obsoletes or updates 🦋

Abstract

this doc defines the "api-catalog" well-known URI and link relation 💖 its whole purpose is to make APIs easy for machines to find and use automatically 🤖✨ a request to the api-catalog resource gives you back a document with info about the Publisher's APIs and links to them. it's giving organisation, no cap 🫶

Status of This Memo

this is an Internet Standards Track document 🔥

it's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community. it got public review and was approved for publication by the Internet Engineering Steering Group (IESG). if you want more on Internet Standards, check Section 2 of RFC 7841 📚

for the current status, any errata, and how to send feedback, go to https://www.rfc-editor.org/info/rfc9727 🦋

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 (https://trustee.ietf.org/license-info) as they stand on the date of publication. please read those carefully, bestie, because they explain your rights and restrictions for this doc 🧾

if you extract Code Components from this document, they must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions. they come without warranty, as described in the Revised BSD License ⚠️

Table of Contents 🧚

1.  Introduction
  1.1.  Goals and Non-Goals
  1.2.  Notational Conventions
2.  Using the "api-catalog" Well-Known URI
3.  The api-catalog Link Relation
  3.1.  Using Additional Link Relations
4.  The API Catalog Document
  4.1.  API Catalog Contents
  4.2.  API Catalog Formats
  4.3.  Nesting API Catalog Links
5.  Operational Considerations
  5.1.  Accounting for APIs Distributed Across Multiple Domains
  5.2.  Internal Use of api-catalog for Private APIs
  5.3.  Scalability Guidelines
  5.4.  Monitoring and Maintenance
  5.5.  Integration with Existing API Management Frameworks
6.  Conformance to RFC 8615
  6.1.  Path Suffix
  6.2.  Formats and Associated Media Types
7.  IANA Considerations
  7.1.  The api-catalog Well-Known URI
  7.2.  The api-catalog Link Relation
  7.3.  The api-catalog Profile URI
8.  Security Considerations
9.  References
  9.1.  Normative References
  9.2.  Informative References
Appendix A.  Example API Catalog Documents
  A.1.  Using Linkset with Link Relations Defined in RFC 8631
  A.2.  Using Linkset with Bookmarks
  A.3.  Other API Catalog Formats
  A.4.  Nesting API Catalog Links
Acknowledgements
Author's Address

1. Introduction ✨

okay so, an application can publish APIs to invite requests for interaction from outside parties 💌 but those APIs have to be discovered before anyone can use them. the external party needs to know which APIs a given Publisher exposes, what each one is for, any usage policies, and the endpoint to talk to each API. to make all of that discoverable and usable by automation, this document proposes two things 🌈

  • a well-known URI [WELL-KNOWN], "api-catalog", encoded as a URI reference to an API catalog document describing a Publisher's API endpoints 🎀
  • a link relation [WEB-LINKING], "api-catalog", whose target resource is the Publisher's API catalog document 🔗

1.1. Goals and Non-Goals

the main goal is to make it easy to automatically discover a Publisher's public API endpoints, plus metadata about what each API does and how to use it. we get there with a well-known URI that returns an API catalog document ✨ that document is mainly for machines, so automation can find and use APIs, but it can also link to human-readable docs (see the example in Appendix A.1) 🧠💕

Non-goals: this document does not mandate paths for API endpoints. so it doesn't say my_example_api's endpoint has to be https://www.example.com/.well-known/api-catalog/my_example_api, and it doesn't say it has to be hosted at www.example.com either (though doing so isn't forbidden) 🙈

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 as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. these words can also show up in lower case as plain English words without their normative meanings 💅

the terms "content negotiation" and "status code" come from [HTTP]. the term "well-known URI" comes from [WELL-KNOWN]. the term "link relation" comes from [WEB-LINKING] 📚

the term "Publisher" means an organisation, company, or individual that publishes one or more APIs for use by external third parties 🏢 the fictional Publisher "example" shows up all over the examples, using 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" 🌍 the .com and .net Top-Level Domains (TLDs) and the subdomains are only there to show that "example" can spread its API portfolio across several domains it has authority over 🦋 if the Publisher "example" is not the authority for a given _.example._ domain, the text says so explicitly 👀

in this document, "API" means the specification resources an external party needs to build software that uses the Publisher's API. for "private" APIs, that party is an internal one instead 🔒

the spec recommends using TLS, so "HTTPS" and "https://" show up throughout 🔐

2. Using the "api-catalog" Well-Known URI 🔍

the api-catalog well-known URI is meant for HTTPS servers that publish APIs 🖥️

  • The API catalog MUST be named "api-catalog" in a well-known location as described by [WELL-KNOWN]. 💖
  • The location of the API catalog document is decided by the Publisher. The /.well-known/api-catalog URI gives you a handy reference to that location 🧭

a Publisher that supports this URI:

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

this doc introduces a new link relation [WEB-LINKING], api-catalog. it identifies a target resource that represents a list of APIs available from the Publisher of the link context 💜 the target resource URI can be /.well-known/api-catalog or any other URI the Publisher picks 🌸

for example, the Publisher "example" could include the api-catalog link relation in the HTTP header and/or the content payload when it responds 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>

inside an API catalog document, the "item" [RFC6573] link relation identifies a target resource that represents an API that is a member of the API catalog 🎁

other link relations can also show up in an API catalog to convey metadata descriptions for API links 💅

4. The API Catalog Document 📖

the API catalog is a document that lists a Publisher's APIs 💅 the Publisher can host the API catalog document at any URI(s) they like. for example, the API catalog document URI https://www.example.com/my_api_catalog.json can be requested directly, or through a request to https://www.example.com/.well-known/api-catalog, which the Publisher resolves to https://www.example.com/my_api_catalog ✨

4.1. 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 [OAS] definitions for each API, and so on. 🧾
  • 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 Appendix A.2 for an example). 🫶

4.2. API Catalog Formats 🌈

  • The Publisher MUST publish the API catalog document in the Linkset format application/linkset+json (Section 4.2 of [RFC9264]). 💖
  • The Linkset SHOULD include a profile parameter (Section 5 of [RFC9264]) with a Profile URI [RFC7284] value of https://www.rfc-editor.org/info/rfc9727, to show that the Linkset represents an API catalog document as defined above 🎀
  • Appendix A includes example API catalog documents based on the Linkset format 📚

the Publisher MAY make additional formats available through content negotiation (Section 12 of [HTTP]) at their /.well-known/api-catalog location. Appendix A.3 has a non-exhaustive list of such formats that support automated discovery and machine (and human) usage of a Publisher's APIs 🦋

if a Publisher already lists their APIs in a format other than Linkset but still wants to use the /.well-known/api-catalog URI, then:

  • They MUST also implement a Linkset with, at minimum, hyperlinks to API endpoints; see Appendix A.2. 💅
  • They MAY support content negotiation at the /.well-known/api-catalog URI so they can return their existing format. 🌸

an API catalog can contain links to other API catalogs too, by using the "api-catalog" relation type for each link 🧚 an example is in Appendix A.4 ✨

5. Operational Considerations 🛠️

(part 2 is coming up next, bestie 💖)

5.1. Accounting for APIs Distributed Across Multiple Domains

okay so a Publisher (let's say "example") can have their APIs living on a bunch of domains they run, like www.example.com, developer.example.com, apis.example.com, apis.example.net, and so on 🌐. They might even pay a third-party API hosting provider to host stuff on a totally separate domain 💅.

so to keep track of all of that, it is RECOMMENDED that:

  • The Publisher also publish the api-catalog well-known URI on 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 picks one of their instances of /.well-known/api-catalog as the canonical reference to where the latest API catalog lives. The physical location of the API catalog document is decided by the Publisher and may change, so the Publisher's other instances of /.well-known/api-catalog should redirect to this canonical instance to make sure the latest API catalog is what gets returned 🎀

for example, if the Publisher's main 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 👑. and if the Publisher is also the domain authority for www.example.net (which hosts a selection of their APIs too), 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 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"
  }
 ]
}

5.2. Internal Use of api-catalog for Private APIs

so a Publisher might want to use the api-catalog well-known URI on their internal network 🏢. the idea is to point authorised users (think company employees) towards internal/private APIs that aren't meant for third-party use 🔐. heads up though, this can bring extra security considerations, which you'll find in Section 8 💀.

5.3. Scalability Guidelines

okay, so if a Publisher has a LOT of APIs spread across multiple domains, two challenges can pop up 😭:

  • Keeping the catalog entries up to date and fixing any errors
  • Keeping the catalog size small, so network and client-processing overheads don't get out of hand

in both cases, the Publisher can benefit from grouping their APIs. they make an API catalog document for each group and then use the main API catalog hosted at /.well-known/api-catalog to link to those 🧚. the grouping can be by business category (like "gaming APIs" or "anti-fraud APIs"), by technology category (like "IOT", "networks", or "AI"), or by any other criterion they like 🌈. the grouping can even be implicit if the Publisher already published their APIs across multiple domains, like gaming.example.com or iot.example.net ✨.

Section 4.3 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 cut down the network overhead of large API catalogs 🗜️.

5.4. 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 the availability of the API catalog and consider alternate means to resolve requests to /.well-known/api-catalog during planned downtime of hosts 🛠️
  • Performance. the APIs listed in an API catalog can demand high transactions per second and low-latency responses, but fetching the catalog itself (the thing that helps you discover those APIs) is less likely to have strict performance demands 🏃‍♀️. that said, the Publisher should monitor how long it takes to respond to a request for the API catalog and figure out any necessary improvements (same as any other Web resource they serve) 📈. for large API catalogs, the Publisher should consider the techniques described in Section 5.3
  • Usage. since the whole goal of the api-catalog well-known URI is to help people discover APIs, the Publisher may want to correlate requests to /.well-known/api-catalog with the later requests made to the API URIs listed in the catalog 👀
  • Current data. the Publisher should include removing stale API entries from the API catalog as part of their API release lifecycle 🧹. the Publisher MAY decide to include metadata about legacy API versions or deprecated APIs, so users of those APIs can find 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 (like making sure the JSON syntax is valid) and linting to enforce business rules, such as removing duplicate entries and making sure descriptions are named correctly with valid values 🔍. a proofread of the API catalog as part of the API release lifecycle is RECOMMENDED to catch errors in business grammar (for example, an API entry that is described with valid syntax but has been given an incorrect or outdated description) 📝
  • Security best practice. see Section 8 🔐

5.5. Integration with Existing API Management Frameworks

a Publisher might already use an API management framework to put together their API portfolio 🗂️. these frameworks usually handle publishing API endpoint URIs, deprecating and redirecting legacy API versions, API usage policies and documentation, and so on 📚. the api-catalog well-known URI and API catalog document are meant to complement these frameworks by helping people discover what the framework outputs (API endpoints, usage policies, and documentation). they are NOT meant to replace any existing API discovery mechanisms the framework already has 💖.

framework providers can produce an API catalog and publish the /.well-known/api-catalog URI as a final pre-release (or post-release) step in their release management workflow 🚀. the following steps are recommended.

if the /.well-known/api-catalog URI has NOT been published before, the framework provider should:

  • Collate and check the metadata for each API that will be included in the API catalog. this metadata probably already exists in the framework 📋
  • Figure out which metadata to include in the API catalog, following the requirements in Section 4.1 and the considerations in Section 5 🤔
  • Map the chosen metadata to the format(s) described in Section 4.2. the structure suggested in Appendix 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 in Section 4.1; in that case, the structure suggested in Appendix A can be used and adapted (making sure it complies with [RFC9264]) to reflect the nature of the chosen metadata 🧩
  • Publish the /.well-known/api-catalog URI following the guidance in Section 2 🎉

if the /.well-known/api-catalog URI HAS been published before, the framework provider should:

  • Include a step in the release management lifecycle to refresh the API catalog whenever API hyperlinks or published metadata change. this could mean setting triggers on certain metadata fields, so that when they get updated in pre-production on the API framework, those updates are pushed to a pre-production copy of the API catalog, which then goes live when the release is published by the framework 🔁✨

6. Conformance to RFC 8615

okay now we check that this thing actually follows the rules 🤓. the requirements in Section 3 of [WELL-KNOWN] for defining Well-Known URIs are met, as described in the following subsections 💅.

6.1. Path Suffix

the api-catalog URI SHALL be appended to the /.well-known/ path-prefix for "well-known locations" 🛣️.

6.2. Formats and Associated Media Types

a /.well-known/api-catalog location MUST support the Linkset [RFC9264] format of application/linkset+json, and it MAY also support the other formats via content negotiation 🎀.

7. IANA Considerations

the paperwork part 📑. this is where the registrations get logged with IANA so everyone knows what's what 🗃️.

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

this specification registers the "api-catalog" link relation in the "Link Relation Types" registry, following the procedures in Section 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

8. Security Considerations 🔒✨

Okay bestie, this section is SERIOUS 💀 but also the most iconic part, because it's where we protect the catalog from getting messed with. Here's the vibe for all scenarios:

  • TLS: TLS SHOULD be used, which means /.well-known/api-catalog should only be served over HTTPS so nobody can tamper with the API catalog 🔐
  • Security guidance: The Publisher SHOULD take into account the security considerations from Section 4 of [WELL-KNOWN] 📚
  • Review before launch: The Publisher SHOULD do a security and privacy review of the API catalog before deploying it. The goal is to make sure it doesn't leak personal, business, or other sensitive metadata, and doesn't expose any vulnerability related to the APIs it lists 🙈
  • Read-only access: The Publisher SHOULD enforce read-only privileges for external requests to .well-known/api-catalog, and for internal systems and roles that monitor that URI. Write privileges SHOULD only go to roles that update the API catalog and/or the forwarding rewrite rules for the .well-known/api-catalog URI 🫶
  • Rate limiting: Like any Web offering, it is RECOMMENDED to apply rate limiting to help stop abuse and prevent denial-of-service attacks on the API catalog endpoint 🚦

For the public-facing APIs scenario, security teams SHOULD also audit the API catalog to make sure no APIs meant only for internal use got included by accident. For example, a catalog hosted on https://developer.example.com should not expose unnecessary metadata about internal domains like https://internal.example.com 👀

For the internal/private APIs scenario, the Publisher SHOULD take steps to put proper controls in place, such as Cross-Origin Resource Sharing (CORS) policies and access control lists. The idea is that only authorised roles and systems can access an internal api-catalog well-known URI 🔑

A comprehensive API catalog that gets audited regularly can help the Publisher decommission "zombie" APIs, meaning legacy or obsolete APIs that should no longer be available. These APIs are a security vulnerability because they're unlikely to be supported, monitored, patched, or updated. Zombie APIs are NOT a vibe 🧟

Last thing: the registration of domain names and the policies around them are out of scope for this document 🙃

9. References

9.1. Normative References

Here are the normative references, the ones you genuinely need to read to understand the spec 📖

[HTTP]     Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
           Ed., "HTTP Semantics", STD 97, RFC 9110,
           DOI 10.17487/RFC9110, June 2022,
           <https://www.rfc-editor.org/info/rfc9110>.

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <https://www.rfc-editor.org/info/rfc2119>.

[RFC6573]  Amundsen, M., "The Item and Collection Link Relations",
           RFC 6573, DOI 10.17487/RFC6573, April 2012,
           <https://www.rfc-editor.org/info/rfc6573>.

[RFC7284]  Lanthaler, M., "The Profile URI Registry", RFC 7284,
           DOI 10.17487/RFC7284, June 2014,
           <https://www.rfc-editor.org/info/rfc7284>.

[RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
           2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
           May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[RFC9264]  Wilde, E. and H. Van de Sompel, "Linkset: Media Types and
           a Link Relation Type for Link Sets", RFC 9264,
           DOI 10.17487/RFC9264, July 2022,
           <https://www.rfc-editor.org/info/rfc9264>.

[WEB-LINKING]
           Nottingham, M., "Web Linking", RFC 8288,
           DOI 10.17487/RFC8288, October 2017,
           <https://www.rfc-editor.org/info/rfc8288>.

[WELL-KNOWN]
           Nottingham, M., "Well-Known Uniform Resource Identifiers
           (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019,
           <https://www.rfc-editor.org/info/rfc8615>.

9.2. Informative References

These ones are the helpful extras that give more context. Not strictly required, but very much worth a look ✨

[APIsjson] Lane, K. and S. Willmott, "API Discovery Format", 6
           November 2024,
           <https://apisjson.org/format/apisjson_0.19.txt>.  Latest
           version available at <https://apisjson.org/>.

[HAL]      Kelly, M., "JSON Hypertext Application Language", Work in
           Progress, Internet-Draft, draft-kelly-json-hal-11, 19
           October 2023, <https://datatracker.ietf.org/doc/html/
           draft-kelly-json-hal-11>.

[OAS]      Miller, D., Ed., Andrews, H., Ed., Whitlock, J., Ed.,
           Mitchell, L., Ed., Gardiner, M., Ed., Quintero, M., Ed.,
           Kistler, M., Ed., Handl, R., Ed., and R. Ratovsky, Ed.,
           "OpenAPI Specification v3.1.0", 24 October 2024,
           <https://spec.openapis.org/oas/latest>.  Latest version
           available at <https://spec.openapis.org/oas/latest.html>.

[RESTdesc] Verborgh, R., Mannens, E., Van de Walle, R., and T.
           Steiner, "RESTdesc", 2025,
           <https://restdesc.org/about/descriptions>.

[RFC8631]  Wilde, E., "Link Relation Types for Web Services",
           RFC 8631, DOI 10.17487/RFC8631, July 2019,
           <https://www.rfc-editor.org/info/rfc8631>.

[WebAPIext]
           Ralphson, M., Ed. and N. Evans, Ed., "WADG0001 WebAPI type
           extension", Draft Community Group Report, 8 July 2020,
           <https://webapi-discovery.github.io/rfcs/rfc0001.html>.

Appendix A. Example API Catalog Documents

This section is informative, so it's not required reading. It's basically a bunch of examples of what an API catalog document can look like using the Linkset format 🎀

This example uses the Linkset format [RFC9264] along with the following link relations from [RFC8631]:

  • "service-desc": links to a description of the API that's mainly for machines to read, like an [OAS] specification in YAML or JSON 🤖
  • "service-doc": links to API documentation that's mainly for humans to read. An example of human-readable docs is the IETF Internet-Draft submission API instructions at <https://datatracker.ietf.org/api/submission> 🧑‍💻
  • "service-meta": links to extra metadata about the API, mainly for machines 🗂️
  • "status": links to the API status (like an API "health" check) for machines, humans, or both 💚

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"
    }
   ]
  }
 ]
}

A.2. Using Linkset with Bookmarks

This one also uses the Linkset format [RFC9264], but lists the API endpoints as an array of bookmarks 🔖 Every link shares the same context anchor (the well-known URI of the API catalog) and the "item" [RFC9264] link relation, which marks them as items in the catalog. The point is that when a machine client follows a bookmark link, it can find out the purpose and usage policy for each API, so the document behind the bookmark link should support that, ngl 💅

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"}
     ]
   }
 ]
}

A.3. Other API Catalog Formats

Here's a non-exhaustive list of other API catalog document formats you might see out in the wild 🌈

  • 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].

In this example, a request to the /.well-known/api-catalog URI gives back an array of links with the relation type "api-catalog". This is handy for Publishers with tons of APIs who want to group them into smaller catalogs, as described in Section 5.3 🧩

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

Huge thanks to everyone who reviewed, suggested, and supported this work, you're literally the reason it's so good 🫶🌸 That's Jan Algermissen, Phil Archer, Tim Bray, Ben Bucksch, Sanjay Dalal, David Dong, Erik Kline, Mallory Knodel, Murray Kucherawy, Max Maton, Darrel Miller, Mark Nottingham, Roberto Polli, Joey Salazar, Rich Salz, Herbert Van De Sompel, Orie Steele, Tina Tsou, Gunter Van de Velde, Éric Vyncke, and Erik Wilde 👑

Author's Address

Kevin Smith Vodafone Email: kevin.smith@vodafone.com URI: https://www.vodafone.com 💜

📦 where this page comes from