<?xml version="1.0" encoding="UTF-8"?>
  <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
  <!-- generated by https://github.com/cabo/kramdown-rfc version 1.7.5 (Ruby 2.6.10) --> version='1.0' encoding='utf-8'?>

<!DOCTYPE rfc [
  <!ENTITY nbsp    "&#160;">
  <!ENTITY zwsp   "&#8203;">
  <!ENTITY nbhy   "&#8209;">
  <!ENTITY wj     "&#8288;">
]>

<?rfc tocindent="yes"?>
<?rfc strict="yes"?>
<?rfc compact="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>

<rfc xmlns:xi="http://www.w3.org/2001/XInclude" ipr="trust200902" submissionType="IETF" docName="draft-ietf-httpapi-api-catalog-08" number="9727" category="std" consensus="true" tocInclude="true" sortRefs="true" symRefs="true"> symRefs="true" version="3" xml:lang="en" updates="" obsoletes="">

<!-- [rfced] FYI - We have updated the short title of the document,
which appears in the running header in the PDF output, as follows.
Please review and let us know any objections.

Original:
  api-catalog well-known URI

Current:
  api-catalog: A Well-Known URI
-->
  <front>
    <title abbrev="api-catalog well-known abbrev="api-catalog: A Well-Known URI">api-catalog: a well-known A Well-Known URI and link relation Link Relation to help discovery Help Discovery of APIs</title>
    <seriesInfo name="RFC" value="9727"/>
    <author initials="K." surname="Smith" fullname="Kevin Smith">
      <organization>Vodafone</organization>
      <address>
        <email>kevin.smith@vodafone.com</email>
        <uri>https://www.vodafone.com</uri>
      </address>
    </author>
    <date />

    <area>IETF</area>

    <keyword>internet-draft</keyword> month="June" year="2025"/>
    <area>WIT</area>
    <workgroup>httpapi</workgroup>

<!-- [rfced] Please insert any keywords (beyond those that appear in
the title) for use on https://www.rfc-editor.org/search. -->

<keyword>example</keyword>

    <abstract>

<?line 83?>
      <t>This document defines the "api-catalog" well-known well-know  URI and link
      relation. It is intended to facilitate automated discovery and usage of
      published APIs. Application Programming Interfaces (APIs). A request to the
      api-catalog resource will return a document providing information about,
      and links to, the publisher's Publisher's APIs.</t>
    </abstract>

    <note title="About This Document" removeInRFC="true">
      <t>
        The latest revision of this draft can be found at <eref target="https://ietf-wg-httpapi.github.io/api-catalog/draft-ietf-httpapi-api-catalog.html"/>.
        Status information for this document may be found at <eref target="https://datatracker.ietf.org/doc/draft-ietf-httpapi-api-catalog/"/>.
      </t>
      <t>
        Discussion of this document takes place on the
        Building Blocks for HTTP APIs Working Group mailing list (<eref target="mailto:httpapi@ietf.org"/>),
        which is archived at <eref target="https://mailarchive.ietf.org/arch/browse/httpapi/"/>.
        Subscribe at <eref target="https://www.ietf.org/mailman/listinfo/httpapi/"/>.
      </t>
      <t>Source for this draft and an issue tracker can be found at
        <eref target="https://github.com/ietf-wg-httpapi/api-catalog"/>.</t>
    </note>
  </front>
  <middle>

<?line 91?>

<section anchor="introduction"><name>Introduction</name> anchor="introduction">
      <name>Introduction</name>
      <t>An application may publish Application Programming Interfaces (APIs) APIs
to encourage requests for interaction from external parties. Such
APIs must be discovered before they may be used - used, i.e., the external
party needs to know what APIs a given publisher Publisher exposes, their
purpose, any policies for usage, and the endpoint to interact with
each API. To facilitate automated discovery of this information, information
and automated usage of the APIs, this document proposes:</t>

<t><list style="symbols">
      <ul spacing="normal">
        <li>
          <t>a well-known URI <xref target="WELL-KNOWN"/>, target="RFC8615"/>, 'api-catalog', that is encoded as a URI
reference to an API catalog document describing a Publisher's API
endpoints.</t>
        </li>
        <li>
          <t>a link relation <xref target="WEB-LINKING"/>, target="RFC8288"/>, 'api-catalog', of which the target
resource is the Publisher's API catalog document.</t>
</list></t>
        </li>
      </ul>
      <section anchor="goals"><name>Goals anchor="goals">
        <name>Goals and non-goals</name> Non-Goals</name>
<!-- [rfced] Are the goals listed in Section 1.1 specified for api-catalog or
for this document?

Current:
   The primary goal 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.

Perhaps:
   The primary goal for api-catalog 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.

Or:
   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.
-->
<t>The primary goal 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 <xref target="api-catalog-example-rfc8615"/>).</t>
        <t>Non-goals: this This document does not mandate paths for API endpoints. endpoints, i.e., it does not mandate that my_example_api's endpoint should be
<spanx style="verb">https://www.example.com/.well-known/api-catalog/my_example_api</spanx>,
<tt>https://www.example.com/.well-known/api-catalog/my_example_api</tt>, nor
even to be hosted at www.example.com (although it is not forbidden to
do so).</t>
      </section>
      <section anchor="notational-conventions"><name>Notational anchor="notational-conventions">
        <name>Notational Conventions</name>
        <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
"MAY", "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL
NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
"<bcp14>MAY</bcp14>", and "OPTIONAL" "<bcp14>OPTIONAL</bcp14>" in this document are to be interpreted as
described in BCP 14 BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/> 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.
<?line -8?></t>
        </t>
        <t>The terms "content negotiation" and "status code" are from <xref target="HTTP"/>. target="RFC9110"/>.
The term "well-known URI" is from <xref target="WELL-KNOWN"/>. target="RFC8615"/>.
The term "link relation" is from <xref target="WEB-LINKING"/>.</t> target="RFC8288"/>.</t>
        <t>The term "Publisher" refers to an organisation, company company, or
        individual that publishes one or more APIs for usage use by external third
        parties.  A fictional Publisher named "example" is used throughout
        this document.  The examples use the FQDNs Fully Qualified Domain Names
        (FQDNs) "www.example.com", "developer.example.com"
,"apis.example.com", "developer.example.com", "apis.example.com", "apis.example.net", "gaming.example.com",
"iot.example.net",where the use of and
        "iot.example.net", where the .com and .net TLDs 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.
<!-- [rfced] We find this sentence difficult to parse. We have updated the
text to read as follows. Please let us know any objections.

Original:
   For scenarios
   where the Publisher "example" is not the authority for a given <em>.example.</em>
   _.example._ domain then that is made explicit in the text.

Current:
   Scenarios where the Publisher "example" is not the authority for a
   given _.example._ domain are made explicit in the text.
-->
Scenarios where the Publisher "example" is
        not the authority for a given <em>.example.</em> domain are
        made explicit in the text.</t>
        <t>In this document, "API" means refers to the specification resources required
for an external party (or in the case of 'private' APIs, an internal
party) to implement software which that uses the Publisher's Application
Programming Interface.</t> API.</t>
        <t>The specification recommends the use of TLS, hence TLS. Hence, "HTTPS" and
"https://" are used throughout.</t>
      </section>
    </section>
    <section anchor="usage"><name>Using anchor="usage">
      <name>Using the 'api-catalog' well-known Well-Known URI</name>
      <t>The api-catalog well-known URI is intended for HTTPS servers that
publish APIs.</t>

<t><list style="symbols">
      <ul spacing="normal">
        <li>
          <t>The API catalog MUST <bcp14>MUST</bcp14> be named "api-catalog" in a well-known location
 as described by <xref target="WELL-KNOWN"/>.</t> target="RFC8615"/>.</t>
        </li>
        <li>
          <t>The location of the API catalog document is decided by the Publisher:
the Publisher.
The /.well-known/api-catalog URI provides a convenient reference to
that location.</t>
</list></t>
        </li>
      </ul>
      <t>A Publisher supporting this URI:</t>

<t><list style="symbols">
  <t>SHALL
      <ul spacing="normal">
        <li>
          <t><bcp14>SHALL</bcp14> resolve an HTTPS GET request to /.well-known/api-catalog and
return an API catalog document ( as (as described in <xref target="api-catalog"/> ).</t>
  <t>SHALL target="api-catalog"/>).</t>
        </li>
        <li>
          <t><bcp14>SHALL</bcp14> resolve an HTTPS HEAD request to /.well-known/api-catalog
with a response including a Link header with the relation(s) defined
in <xref target="link-relation"/></t>
</list></t> target="link-relation"/>.</t>
        </li>
      </ul>
    </section>
    <section anchor="link-relation"><name>The anchor="link-relation">
      <name>The api-catalog link relation</name> Link Relation</name>
      <t>This document introduces a new link relation <xref target="WEB-LINKING"/>, target="RFC8288"/>,
"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
<spanx style="verb">https://www.example.com</spanx> :</t>

<figure><sourcecode
<tt>https://www.example.com</tt>:</t>
      <sourcecode type="http-message"><![CDATA[
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>

]]></sourcecode></figure>
]]></sourcecode>
      <section anchor="using-additional-link-relations"><name>Using anchor="using-additional-link-relations">
        <name>Using Additional Link Relations</name>

<!-- [rfced] May we reformat the bulleted list items in Section 3.1 into
paragraph form?

Original:
3.1.  Using additional link relations</name>

<t><list style="symbols"> relations

   *  "item" [RFC6573].  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.

Perhaps:
3.1.  Using Additional Link Relations

   When used in 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 may be utilised in an API catalog to convey
   metadata descriptions for API links.
-->

        <ul spacing="normal">
          <li>
            <t>"item" <xref target="RFC6573"/>. 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.</t>
          </li>
          <li>
            <t>Other link relations may be utilised in an API catalog to convey
metadata descriptions for API links.</t>
</list></t>
          </li>
        </ul>
      </section>
    </section>
    <section anchor="api-catalog"><name>The anchor="api-catalog">
      <name>The API catalog document</name> Catalog Document</name>
      <t>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.
<!-- [rfced] Is "As illustration" meant to be "as illustrated" in this
context? Would "For example" also work here for simplicity?

Original:
   As illustration, the API catalog document URI of
<spanx style="verb">https://www.example.com/my_api_catalog.json</spanx>
   https://www.example.com/my_api_catalog.json can be requested
   directly, or via a request to
<spanx style="verb">https://www.example.com/.well-known/api-catalog</spanx>, https://www.example.com/.well-known/
   api-catalog, which the Publisher will resolve to <spanx style="verb">https://www.example.com/my_api_catalog</spanx>.</t>

<section anchor="api-catalog-contents"><name>API
   https://www.example.com/my_api_catalog.

Perhaps:
   For example, the API catalog contents</name>

<t>The 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.
-->
As illustration, the API catalog document URI of
<tt>https://www.example.com/my_api_catalog.json</tt> can be requested
directly or via a request to
<tt>https://www.example.com/.well-known/api-catalog</tt>, which the
Publisher will resolve to <tt>https://www.example.com/my_api_catalog</tt>.</t>
      <section anchor="api-catalog-contents">
        <name>API Catalog Contents</name>
<!-- [rfced] May we split the sentence below into two sentences to
improve readability?

Original:
   The API catalog MUST include hyperlinks to API endpoints, and is
   RECOMMENDED to include useful metadata, such as usage policies, API
   version information, links to the OpenAPI Specification [OAS]
   definitions for each API, etc.

Perhaps:
   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, etc.
-->

        <t>The API catalog <bcp14>MUST</bcp14> include hyperlinks to API endpoints,
and is <bcp14>RECOMMENDED</bcp14> to include useful metadata, such as usage
policies, API version information, links to the OpenAPI Specification
<xref target="OAS"></xref> target="OAS"/> definitions for each API, etc. If the Publisher does not
include that metadata directly in the API catalog document, they
SHOULD
<bcp14>SHOULD</bcp14> make that metadata available at the API endpoint URIs they
have listed (see <xref target="api-catalog-example-linkset-bookmarks"/> for
an example).</t>
      </section>
      <section anchor="api-catalog-formats"><name>API catalog formats</name> anchor="api-catalog-formats">
        <name>API Catalog Formats</name>
        <t>The Publisher MUST <bcp14>MUST</bcp14> publish the API catalog document in the Linkset
format <spanx style="verb">application/linkset+json</spanx> (section 4.2 of <xref <tt>application/linkset+json</tt> (<xref section="4.2" sectionFormat="of" target="RFC9264"/>).
The Linkset SHOULD <bcp14>SHOULD</bcp14> include a profile parameter (section 5 of
<xref (<xref section="5" sectionFormat="of" target="RFC9264"/>) with a Profile URI <xref target="RFC7284"/> value of 'THIS-RFC-URL' 'https://www.rfc-editor.org/info/rfc9727'
to indicate the Linkset is representing an API catalog document as
defined above. Appendix A <xref target="api-catalog-example-linkset"/> includes example API catalog documents
based on the Linkset format.</t>

<t>The

<!-- [rfced] FYI - We have updated the citation below since Section 5.3 of
[HTTP] doesn't appear to mention "content negotiation", while Section 12 of
[HTTP] is titled "Content Negotiation". Please review.

Original:
   The Publisher MAY make additional formats available via content
   negotiation (section 5.3 of <xref target="HTTP"/>) [HTTP]) to their /.well-known/api-catalog
   location.

Current:
   The Publisher MAY make additional formats available via content
   negotiation (Section 12 of [HTTP]) to their /.well-known/api-catalog
   location.
-->
        <t>The Publisher <bcp14>MAY</bcp14> make additional formats available via
content negotiation (<xref section="12" sectionFormat="of" target="RFC9110"/>) to their
/.well-known/api-catalog location. A non-exhaustive list of such
formats that support the automated discovery, discovery and machine (and
human) usage of a Publisher's APIs, APIs is listed at
<xref target="api-catalog-other-formats"/>. If a Publisher already lists their
APIs in a format other than Linkset Linkset, but wish wishes to utilise the
/.well-known/api-catalog URI, then:</t>

<t><list style="symbols">
        <ul spacing="normal">
          <li>
            <t>They MUST <bcp14>MUST</bcp14> also implement a Linkset with, at minimum, hyperlinks to
API endpoints - endpoints; see the example of <xref target="api-catalog-example-linkset-bookmarks"/> in Appendix A.</t> target="api-catalog-example-linkset-bookmarks"/>.</t>
          </li>
          <li>
            <t>They MAY <bcp14>MAY</bcp14> support content negotiation at the
/.well-known/api-catalog URI to allow for the return of their existing format to be
returned.</t>
</list></t> format.</t>
          </li>
        </ul>
      </section>
      <section anchor="nest"><name>Nesting anchor="nest">
        <name>Nesting API catalog links</name> Catalog Links</name>
        <t>An API catalog may itself contain links to other API catalogs, catalogs by using
        the 'api-catalog' relation type for each link.  An example of this is
        given in <xref target="api-catalog-example-linkset-nesting"/>.</t>
      </section>
    </section>
    <section anchor="operations"><name>Operational considerations</name> anchor="operations">
      <name>Operational Considerations</name>
      <section anchor="multiple_domains"><name>Accounting anchor="multiple_domains">
        <name>Accounting for APIs distributed across multiple domains</name> Distributed Across Multiple Domains</name>
        <t>A Publisher ("example") may have their APIs hosted across multiple
domains that they manage: manage, e.g., at <spanx style="verb">www.example.com</spanx>,
<spanx style="verb">developer.example.com</spanx>, <spanx style="verb">apis.example.com</spanx>,
<spanx style="verb">apis.example.net</spanx> <tt>www.example.com</tt>,
<tt>developer.example.com</tt>, <tt>apis.example.com</tt>,
<tt>apis.example.net</tt>, etc. They may also use a third-party API
hosting provider which that hosts APIs on a distinct domain.</t>
        <t>To account for this scenario, it is RECOMMENDED <bcp14>RECOMMENDED</bcp14> that:</t>

<t><list style="symbols">
        <ul spacing="normal">
          <li>
            <t>The Publisher also publish the api-catalog well-known URI at each
 of their API domains e.g.
 <spanx style="verb">https://apis.example.com/.well-known/api-catalog</spanx>,
 <spanx style="verb">https://developer.example.net/.well-known/api-catalog</spanx> domains, e.g., <tt>https://apis.example.com/.well-known/api-catalog</tt>,
 <tt>https://developer.example.net/.well-known/api-catalog</tt>, etc.</t>
          </li>
          <li>
            <t>An HTTPS GET request to any of these URIs returns the same result,
 namely, the API catalog document.</t>
  <t>Since the physical location of the API catalog document is decided
 by the Publisher, and may change, the
          </li>
          <li>
            <t>The Publisher choose one of their
instances of /.well-known/api-catalog as a canonical reference to
the location of the latest API catalog. 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.</t>
</list></t>
          </li>
        </ul>
        <t>For example, if the Publisher's primary API portal is
<spanx style="verb">https://apis.example.com</spanx>,
<tt>https://apis.example.com</tt>, then
<spanx style="verb">https://apis.example.com/.well-known/api-catalog</spanx>
<tt>https://apis.example.com/.well-known/api-catalog</tt> should resolve to
the location of the Publisher's latest API catalog document. If the
Publisher is also the domain authority for <spanx style="verb">www.example.net</spanx>, <tt>www.example.net</tt>,
which also hosts a selection of their APIs, then a request to
<spanx style="verb">https://www.example.net/.well-known/api-catalog</spanx>
<tt>https://www.example.net/.well-known/api-catalog</tt> should redirect
to <spanx style="verb">https://apis.example.com/.well-known/api-catalog</spanx> .</t>

<t>If <tt>https://apis.example.com/.well-known/api-catalog</tt>.</t>

<!-- [rfced] May we rephrase the following sentence for clarity?

Original:
   If the Publisher is not the domain authority for
<spanx style="verb">www.example.net</spanx> www.example.net -
   or any third-party domain that hosts any of the Publisher's APIs - then the
   Publisher MAY include a link in its own API catalog to that third-party
   domain's API catalog.

Perhaps:
   If the Publisher or any third-party domain that hosts any of the
   Publisher's APIs is not the domain authority for www.example.net, then the
   Publisher MAY include a link in its own API catalog to that third-party
   domain's API catalog.
-->
<t>If the Publisher is not the domain authority for
<tt>www.example.net</tt> --  or any third-party domain that hosts any
of the Publisher's APIs -- then the Publisher <bcp14>MAY</bcp14> include a link in
its own API catalog to that third-party domain's API catalog.
For example, the API catalog available
at <spanx style="verb">https://apis.example.com/.well-known/api-catalog</spanx>) <tt>https://apis.example.com/.well-known/api-catalog</tt> may list APIs
hosted at <spanx style="verb">apis.example.com</spanx> <tt>apis.example.com</tt> and also link to the API catalog hosted
at <spanx style="verb">https://www.example.net/.well-known/api-catalog</spanx> <tt>https://www.example.net/.well-known/api-catalog</tt> using the
"api-catalog" link relation:</t>

<figure><sourcecode
        <sourcecode type="json"><![CDATA[
{
  "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"
    }
  ]
}
]]></sourcecode></figure>
]]></sourcecode>
      </section>
      <section anchor="internal-use"><name>Internal use anchor="internal-use">
        <name>Internal Use of api-catalog for private Private APIs</name>
        <t>A Publisher may wish to use the api-catalog well-known URI on their
internal network, network to signpost authorised users (e.g. (e.g., company
employees) towards internal/private APIs not intended for third-party
use. This scenario may incur additional security considerations, considerations as
noted in <xref target="security"/>.</t>
      </section>
      <section anchor="scalability"><name>Scalability guidelines</name> anchor="scalability">
        <name>Scalability Guidelines</name>
        <t>In cases where a Publisher has a large number of APIs, APIs potentially
deployed across multiple domains, then two challenges may arise:</t>

<t><list style="symbols">
        <ul spacing="normal">
          <li>
            <t>Maintaining the catalog entries to ensure they are up to date and
correcting any errors corrected.</t> errors.</t>
          </li>
          <li>
            <t>Restricting the catalog size to help reduce network and
client-processing overheads.</t>
</list></t>
          </li>
        </ul>
        <t>In both cases cases, a Publisher may benefit from grouping their APIs,
providing an API catalog document for each group - and use using the main
API catalog hosted at /.well-known/api-catalog to provide links to
these. For example example, a Publisher may decide to group their APIs
according to a business category (e.g. (e.g., 'gaming APIs', 'anti-fraud
APIs etc.) or
APIs', etc.), a technology category (e.g. ''IOT', (e.g., 'IOT', 'networks', 'AI' 'AI',
etc.), or any other criterion.

<!--[rfced] As this sentence reads awkwardly due to the two instances of
"already", may we remove the first one?

Original:
   This grouping may already be implicit
   where the Publisher has already published their APIs across multiple
   domains, e.g. at <spanx style="verb">gaming.example.com</spanx>, <spanx style="verb">iot.example.net</spanx>, gaming.example.com, iot.example.net, etc.

Perhaps:
   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.
-->

This grouping may already be implicit
where the Publisher has already published their APIs across multiple
domains, e.g., at <tt>gaming.example.com</tt>, <tt>iot.example.net</tt>, etc.</t>
        <t><xref target="nest"/> shows how the API catalog at
/.well-known/api-catalog can use the api-catalog link relation to
point to other API catalogs.</t>
        <t>The Publisher SHOULD <bcp14>SHOULD</bcp14> consider caching and compression
techniques to reduce the network overhead of large API catalogs.</t>
      </section>
      <section anchor="maintenance"><name>Monitoring anchor="maintenance">
        <name>Monitoring and maintenance</name> Maintenance</name>
        <t>Publishers are RECOMMENDED <bcp14>RECOMMENDED</bcp14> to follow operational best practice when
hosting API catalog(s), including including, but not limited to:</t>

<t><list style="symbols">
        <ul spacing="normal">
          <li>
            <t>Availability. The Publisher should monitor availability of the API
catalog,
catalog and consider alternate means to resolve requests to
/.well-known/api-catalog during planned downtime of hosts.</t>
          </li>
          <li>
            <t>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, 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
<xref target="scalability"/>.</t>
          </li>
          <li>
            <t>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.</t>
          </li>
          <li>
            <t>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 <bcp14>MAY</bcp14> decide to include metadata regarding legacy API
versions or deprecated APIs to help users of those APIs discover
up-to-date alternatives.</t>
          </li>
          <li>
            <t>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. (e.g., to ensure valid JSON syntax)
and linting to enforce business rules - 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 <bcp14>RECOMMENDED</bcp14> 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.)</t>
          </li>
          <li>
            <t>Security best practice, as set out in practice. See <xref target="security"/>.</t>
</list></t>
          </li>
        </ul>
      </section>
      <section anchor="integration"><name>Integration anchor="integration">
        <name>Integration with existing Existing API management frameworks</name> Management Frameworks</name>
        <t>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 policies, and
documentation - -- and are not intended to replace any existing
API discovery mechanisms the framework has implemented.</t>
        <t>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:</t> recommended.</t>
        <t>If the /.well-known/api-catalog URI has not been published previously
, previously, the framework provider should:</t>

<t><list style="symbols">
        <ul spacing="normal">
          <li>
            <t>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.</t>
          </li>
          <li>
            <t>Determine which metadata to include in the API catalog, catalog following
the requirements set out in <xref target="api-catalog-contents"/> and the
considerations set out in <xref target="operations"/>.</t>
          </li>
          <li>
            <t>Map the chosen metadata to the format(s) described in
<xref target="api-catalog-formats"/>. Where The structure suggested in
<xref target="api-catalog-example-linkset-bookmarks"/> may be followed where only the hyperlinks to APIs are to be
included in the API catalog, then the structure suggested in
<xref target="api-catalog-example-linkset-bookmarks"/> may be followed. catalog. Where
possible
possible, the API catalog should include further metadata per the
guidance in <xref target="api-catalog-contents"/>, target="api-catalog-contents"/>; in which case case, the structure
suggested in <xref target="api-catalog-example-linkset"/> can be utilised and
adapted (ensuring compliance to <xref target="RFC9264"/>) to reflect the nature
of the chosen metadata.</t>
          </li>
          <li>
            <t>Publish the /.well-known/api-catalog URI following the guidance set
out in <xref target="usage"/>.</t>
</list></t>
          </li>
        </ul>
        <t>If the /.well-known/api-catalog URI has previously been published,
the framework provider should:</t>

<t><list style="symbols">
        <ul spacing="normal">
          <li>
            <t>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.</t>
</list></t>
          </li>
        </ul>
      </section>
    </section>
    <section anchor="conform-rfc8615"><name>Conformance anchor="conform-rfc8615">
      <name>Conformance to RFC8615</name> RFC 8615</name>
      <t>The requirements in section 3 of <xref target="WELL-KNOWN"/> section="3" sectionFormat="of" target="RFC8615"/> for defining
Well-Known Uniform Resource Identifiers URIs are met as described in the
following sub-sections.</t> subsections.</t>
      <section anchor="path-suffix"><name>Path suffix</name> anchor="path-suffix">
        <name>Path Suffix</name>
        <t>The api-catalog URI SHALL <bcp14>SHALL</bcp14> be appended to the /.well-known/
path-prefix for "well-known locations".</t>
      </section>
      <section anchor="formats-and-associated-media-types"><name>Formats anchor="formats-and-associated-media-types">
        <name>Formats and associated media types</name> Associated Media Types</name>
        <t>A /.well-known/api-catalog location MUST <bcp14>MUST</bcp14> support the Linkset
<xref target="RFC9264"/> format of application/linkset+json, application/linkset+json and MAY <bcp14>MAY</bcp14>
also support the other formats via content negotiation.</t>
      </section>
<section anchor="registration-of-the-api-catalog-well-known-uri"><name>Registration

<!-- [rfced] We note that Section 6.3 is titled "Registration of the
api-catalog Well-Known URI" and simply states "See Section 7 considerations
below." The section that follows immediately is the api-catalog well-known
URI IANA registration, thus Section 6.3 seems redundant. May we remove this
section to avoid repetition? -->

      <section anchor="registration-of-the-api-catalog-well-known-uri">
        <name>Registration of the api-catalog Well-Known URI</name>
        <t>See <xref target="iana"/> considerations below.</t>
      </section>
    </section>
    <section anchor="iana"><name>IANA anchor="iana">
      <name>IANA Considerations</name>
      <section anchor="the-api-catalog-well-known-uri"><name>The anchor="the-api-catalog-well-known-uri">
        <name>The api-catalog well-known Well-Known URI</name>
        <t>This specification registers the "api-catalog" well-known URI in
        the
Well-Known URI Registry "Well-Known URIs" registry as defined by <xref target="WELL-KNOWN"/>.</t>

<t><list style="symbols">
  <t>URI suffix: api-catalog</t>
  <t>Change Controller: IETF</t>
  <t>Specification document(s): THIS-RFC</t>
  <t>Status: permanent</t>
</list></t>
        target="RFC8615"/>.</t>
        <dl spacing="compact" newline="false">
          <dt>URI Suffix:</dt><dd>api-catalog</dd>
          <dt>Reference:</dt><dd>RFC 9727</dd>
          <dt>Status:</dt><dd>permanent</dd>
          <dt>Change Controller:</dt><dd>IETF</dd>
        </dl>
      </section>
      <section anchor="the-api-catalog-link-relation"><name>The anchor="the-api-catalog-link-relation">
        <name>The api-catalog link relation</name> Link Relation</name>
        <t>This specification registers the "api-catalog" link relation in the "Link Relation Types" registry by
        following the procedures per section 2.1.1.1 of <xref target="WEB-LINKING"/></t>

<t><list style="symbols">
  <t>Relation Name: api-catalog</t>
  <t>Description: Refers section="2.1.1.1" sectionFormat="of"
        target="RFC8288"/>.</t>
        <dl spacing="compact" newline="false">
          <dt>Relation Name:</dt><dd>api-catalog</dd>
          <dt>Description:</dt><dd>Refers to a list of APIs available from the publisher
          Publisher of the link context.</t>
  <t>Reference: THIS-RFC</t>
</list></t> context.</dd>
          <dt>Reference:</dt><dd>RFC 9727</dd>
        </dl>
      </section>

<!-- [rfced] FYI - We have updated "THIS-RFC-URL" to
"https://www.rfc-editor.org/info/rfc9727". Note that this URL
will lead to a page that states "RFC 9727 does not exist" until
this document is published.
-->

      <section anchor="the-api-catalog-profile-uri"><name>The anchor="the-api-catalog-profile-uri">
        <name>The api-catalog Profile URI</name>
        <t>This specification registers "THIS-RFC-URL" "https://www.rfc-editor.org/info/rfc9727" in the "Profile URIs"
        registry according to <xref target="RFC7284"/>.</t>

<t><list style="symbols">
  <t>Profile URI: THIS-RFC-URL</t>
  <t>Common Name: API catalog</t>
  <t>Description: A profile
        <dl spacing="compact" newline="false">
          <dt>Profile URI:</dt><dd>https://www.rfc-editor.org/info/rfc9727</dd>
          <dt>Common Name:</dt><dd>API catalog</dd>
          <dt>Description:</dt><dd>A Profile URI to request or signal a
          Linkset representing an API catalog.</t>
  <t>Reference: THIS-RFC</t>
</list></t>

<t>RFC Editor's Note: IANA is kindly requested to replace all instances
of THIS-RFC and THIS-RFC-URL with the actual RFC number/URL once
assigned.</t> catalog.</dd>
	  <dt>Reference:</dt><dd>RFC 9727</dd>
        </dl>
      </section>
    </section>
    <section anchor="security"><name>Security anchor="security">
      <name>Security Considerations</name>
      <t>For all scenarios:</t>

<t><list style="symbols">
      <ul spacing="normal">
        <li>
          <t>TLS SHOULD <bcp14>SHOULD</bcp14> be used, i.e. i.e., make /.well-known/api-catalog available
exclusively over HTTPS, to ensure no tampering of the API catalog</t> catalog.</t>
        </li>
        <li>
          <t>The Publisher SHOULD <bcp14>SHOULD</bcp14> take into account the Security Considerations security considerations
from section 4 of <xref target="WELL-KNOWN"/>.</t> section="4" sectionFormat="of" target="RFC8615"/>.</t>
        </li>
        <li>
          <t>The Publisher SHOULD <bcp14>SHOULD</bcp14> perform a security and privacy review of the
API catalog prior to deployment, deployment to ensure it does not leak personal,
business
business, or other sensitive metadata, nor expose any vulnerability
related to the APIs listed.</t>
        </li>
        <li>
          <t>The Publisher SHOULD <bcp14>SHOULD</bcp14> enforce read-only privileges for external
requests to .well-known/api-catalog, .well-known/api-catalog and for internal systems and
roles that monitor the .well-known/api-catalog URI. Write privileges
SHOULD
<bcp14>SHOULD</bcp14> 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.</t>
        </li>
        <li>
          <t>As with any Web offering, it is RECOMMENDED <bcp14>RECOMMENDED</bcp14> to apply rate-limiting
measures to help mitigate abuse and prevent Denial-of-Service denial-of-service
attacks on the API catalog endpoint.</t>
</list></t>
        </li>
      </ul>
      <t>For the public-facing APIs scenario: scenario, security teams SHOULD <bcp14>SHOULD</bcp14>
additionally audit the API catalog to ensure no APIs intended solely
for internal use have been mistakenly included. For example, a
catalog hosted on <spanx style="verb">https://developer.example.com</spanx> <tt>https://developer.example.com</tt> should not expose
unnecessary metadata about any internal domains
(e.g. <spanx style="verb">https://internal.example.com</spanx>).</t>
(e.g., <tt>https://internal.example.com</tt>).</t>
      <t>For the internal/private APIs scenario: scenario, the Publisher SHOULD <bcp14>SHOULD</bcp14> take
steps to ensure that appropriate controls - controls, such as CORS Cross-Origin Resource Sharing (CORS) policies and
access control lists - lists, are in place to ensure only authorised roles
and systems may access an internal api-catalog well-known URI.</t>
      <t>A comprehensive API catalog that is regularly audited may assist
the Publisher in decommissioning 'zombie' APIs 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 patched, or updated.</t>
      <t>Note the registration of domain names and associated policies is out
of scope of this document.</t>
    </section>
  </middle>
  <back>
    <displayreference target="RFC9110" to="HTTP"/>
    <displayreference target="RFC8288" to="WEB-LINKING"/>
    <displayreference target="RFC8615" to="WELL-KNOWN"/>
    <displayreference target="I-D.kelly-json-hal" to="HAL"/>
    <references>
      <name>References</name>
      <references title='Normative References' anchor="sec-normative-references">

<reference anchor="HTTP">
  <front>
    <title>HTTP Semantics</title>
    <author fullname="R. Fielding" initials="R." role="editor" surname="Fielding"/>
    <author fullname="M. Nottingham" initials="M." role="editor" surname="Nottingham"/>
    <author fullname="J. Reschke" initials="J." role="editor" surname="Reschke"/>
    <date month="June" year="2022"/>
    <abstract>
      <t>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
        <name>Normative References</name>
        <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9110.xml"/>
        <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8615.xml"/>
        <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8288.xml"/>
        <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>
        <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/>
        <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6573.xml"/>
        <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9264.xml"/>
        <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7284.xml"/>
      </references>
      <references anchor="sec-informative-references">
        <name>Informative References</name>

<!-- [rfced] Please review the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and following reference. The URL uses the "http" and "https" Uniform Resource Identifier (URI) schemes.</t>
      <t>This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230.</t>
    </abstract>
  </front>
  <seriesInfo name="STD" value="97"/>
  <seriesInfo name="RFC" value="9110"/>
  <seriesInfo name="DOI" value="10.17487/RFC9110"/>
</reference>
<reference anchor="WELL-KNOWN">
  <front>
    <title>Well-Known Uniform Resource Identifiers (URIs)</title>
    <author fullname="M. Nottingham" initials="M." surname="Nottingham"/>
    <date month="May" year="2019"/>
    <abstract>
      <t>This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes.</t>
      <t>In doing so, it obsoletes RFC 5785 and updates "latest
published version", which now takes the URI schemes defined in RFC 7230 reader to reserve version 3.1.1 of [OAS]
rather than version 3.1.0 (please note that space. It there has also updates RFC 7595 to track URI schemes that support well-known URIs in their registry.</t>
    </abstract>
  </front>
  <seriesInfo name="RFC" value="8615"/>
  <seriesInfo name="DOI" value="10.17487/RFC8615"/>
</reference>
<reference anchor="WEB-LINKING">
  <front>
    <title>Web Linking</title>
    <author fullname="M. Nottingham" initials="M." surname="Nottingham"/>
    <date month="October" year="2017"/>
    <abstract>
      <t>This specification defines been a model for the relationships between resources on the Web ("links") and the type change
of those relationships ("link relation types").</t>
      <t>It also defines the serialisation of such links in HTTP headers with the Link header field.</t>
    </abstract>
  </front>
  <seriesInfo name="RFC" value="8288"/>
  <seriesInfo name="DOI" value="10.17487/RFC8288"/>
</reference>
<reference anchor="RFC2119">
  <front>
    <title>Key words authors between versions). Please clarify if you wish for use in RFCs this
reference to Indicate Requirement Levels</title>
    <author fullname="S. Bradner" initials="S." surname="Bradner"/>
    <date month="March" year="1997"/>
    <abstract>
      <t>In many standards track documents several words are used point 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.</t>
    </abstract>
  </front>
  <seriesInfo name="BCP" value="14"/>
  <seriesInfo name="RFC" value="2119"/>
  <seriesInfo name="DOI" value="10.17487/RFC2119"/>
</reference>
<reference anchor="RFC8174">
  <front>
    <title>Ambiguity one of Uppercase vs Lowercase in RFC 2119 Key Words</title>
    <author fullname="B. Leiba" initials="B." surname="Leiba"/>
    <date month="May" year="2017"/>
    <abstract>
      <t>RFC 2119 specifies common key words that may be used in protocol specifications. This document aims these specific versions. If you would like
to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.</t>
    </abstract>
  </front>
  <seriesInfo name="BCP" value="14"/>
  <seriesInfo name="RFC" value="8174"/>
  <seriesInfo name="DOI" value="10.17487/RFC8174"/>
</reference>
<reference anchor="RFC6573">
  <front>
    <title>The Item and Collection Link Relations</title>
    <author fullname="M. Amundsen" initials="M." surname="Amundsen"/>
    <date month="April" year="2012"/>
    <abstract>
      <t>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 refer 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.</t>
    </abstract>
  </front>
  <seriesInfo name="RFC" value="6573"/>
  <seriesInfo name="DOI" value="10.17487/RFC6573"/>
</reference>
<reference anchor="RFC9264">
  <front>
    <title>Linkset: Media Types and a Link Relation Type for Link Sets</title>
    <author fullname="E. Wilde" initials="E." surname="Wilde"/>
    <author fullname="H. Van de Sompel" initials="H." surname="Van de Sompel"/>
    <date month="July" year="2022"/>
    <abstract>
      <t>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 latest version, we recommend the following format (with
an added annotation).

Current:
   [OAS]      Darrel Miller, Ed., Jeremy Whitlock, Ed., Marsh Gardiner,
              Ed., Mike Ralphson, Ed., Ron Ratovsky, Ed., and Uri Sarid,
              Ed., "OpenAPI Specification v3.1.0", 15 February 2021,
              <https://spec.openapis.org/oas/latest>.

Perhaps:
   [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.1", 24 October 2024, <https://spec.openapis.org/oas/v3.1.1.html>.
	      Latest version available at <https://spec.openapis.org/oas/latest.html>.
-->

<!-- RE note: XML for representing links in the HTTP "Link" header field. This specification also introduces a link relation type updated reference to support the discovery of sets of links.</t>
    </abstract>
  </front>
  <seriesInfo name="RFC" value="9264"/>
  <seriesInfo name="DOI" value="10.17487/RFC9264"/>
</reference> [OAS]
        <reference anchor="RFC7284"> anchor="OAS" target="https://spec.openapis.org/oas/latest">
          <front>
    <title>The Profile URI Registry</title>
            <title>OpenAPI Specification v3.1.0</title>
            <author initials="D" surname="Miller" role="editor">
             <organization/>
            </author>
	    <author initials="H" surname="Andrews" role="editor">
	     <organization/>
	    </author>
            <author initials="J" surname="Whitlock" role="editor">
              <organization/>
            </author>
	    <author initials="L" surname="Mitchell" role="editor">
	      <orgnaization/>
	    </author>
            <author initials="M" surname="Gardiner" role="editor">
              <organization/>
            </author>
	    <author initials="M" surname="Quintero" role="editor">
	      <organization/>
	    </author>
            <author initials="M" surname="Kistler" role="editor">
              <organization/>
            </author>
	    <author initials="R" surname="Handl" role="editor">
  	      <organization/>
	    </author>
            <author fullname="M. Lanthaler" initials="M." surname="Lanthaler"/> initials="R" surname="Ratovsky" role="editor">
              <organization/>
            </author>
            <date month="June" year="2014"/>
    <abstract>
      <t>This document defines a registry for profile URIs to be used in specifications standardizing profiles.</t>
    </abstract> year="2024" month="October" day="24/>
          </front>
  <seriesInfo name="RFC" value="7284"/>
  <seriesInfo name="DOI" value="10.17487/RFC7284"/>
          <annotation>Latest version available at <eref
          target="https://spec.openapis.org/oas/latest.html" brackets="angle"/>.</annotation>
        </reference>

    </references>

    <references title='Informative References' anchor="sec-informative-references">
-->
        <reference anchor="OAS" target="https://spec.openapis.org/oas/latest">
          <front>
            <title>OpenAPI Specification 3.1.0</title> v3.1.0</title>
            <author initials="" surname="Darrel Miller">
      <organization></organization> initials="D" surname="Miller" role="editor">
              <organization/>
            </author>
            <author initials="" surname="Jeremy Whitlock">
      <organization></organization> initials="J" surname="Whitlock" role="editor">
              <organization/>
            </author>
            <author initials="" surname="Marsh Gardiner">
      <organization></organization> initials="M" surname="Gardiner" role="editor">
              <organization/>
            </author>
            <author initials="" surname="Mike Ralphson">
      <organization></organization> initials="M" surname="Ralphson" role="editor">
              <organization/>
            </author>
            <author initials="" surname="Ron Ratovsky">
      <organization></organization> initials="R" surname="Ratovsky" role="editor">
              <organization/>
            </author>
            <author initials="" surname="Uri Sarid">
      <organization></organization> initials="U" surname="Sarid" role="editor">
              <organization/>
            </author>
            <date year="2021" month="February" day="15"/>
          </front>
        </reference>

<!-- [rfced] Please review the following reference. The date provided for this
reference is 15 September 2020, but the URL lists a date of
9 January 2020. We have updated this reference to use that date.

There are also more recent versions of this specification (see
https://apisjson.org/). The latest version was released on 6 November 2024
(see https://apisjson.org/format/apisjson_0.19.txt). Would you like us to
update the URL to use the most current version and date for this reference?

Current:
   [APIsjson] Lane, K. and S. Willmott, "API Discovery Format", 9
              January 2020,
              <http://apisjson.org/format/apisjson_0.16.txt>.

Perhaps:
   [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/>.
-->

<!-- RE note: XML for updated reference to [APIsjson]
        <reference anchor="APIsjson" target="http://apisjson.org/format/apisjson_0.16.txt"> target="https://apisjson.org/format/apisjson_0.19.txt">
          <front>
    <title>APIs.json</title>
            <title>API Discovery Format</title>
            <author initials="" surname="Kin Lane">
      <organization></organization> initials="K" surname="Lane">
              <organization/>
            </author>
            <author initials="" surname="Steve Willmott">
      <organization></organization> initials="S" surname="Willmott">
              <organization/>
            </author>
            <date year="2020" month="September" day="15"/> year="2024" month="November" day="6"/>
          </front>
	  <annotation>Latest version available at <eref
	  target="https://apisjson.org/"
	  brackets="angle"/>.</annotation>
        </reference>
-->

        <reference anchor="HAL" target="https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-11"> anchor="APIsjson" target="http://apisjson.org/format/apisjson_0.16.txt">
          <front>
    <title>JSON Hypertext Application Language</title>
            <title>API Discovery Format</title>
            <author initials="K" surname="Lane">
              <organization/>
            </author>
            <author initials="" surname="Mike Kelly">
      <organization></organization> initials="S" surname="Willmott">
              <organization/>
            </author>
            <date year="2020" month="September" day="15"/> month="January" day="9"/>
          </front>
        </reference>

<!-- IESG State: Expired as of 02/05/25 -->
	<xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.kelly-json-hal.xml"/>

<!-- [rfced] Please review the reference entry for [RESTdesc]. It uses the
same URL as [APIsjson] (https://apisjson.org/format/apisjson_0.16.txt).

We found the following the URL, which appears to match some of the
original reference information provided: https://restdesc.org/.

Please provide an updated reference entry for [RESTdesc].

Current:
   [RESTdesc] Ruben Verborgh, Erik Mannens, Rick Van de Walle, and
              Thomas Steiner, "RESTdesc", 15 September 2023,
              <http://apisjson.org/format/apisjson_0.16.txt>.
-->
        <reference anchor="RESTdesc" target="http://apisjson.org/format/apisjson_0.16.txt">
          <front>
            <title>RESTdesc</title>
            <author initials="" surname="Ruben Verborgh">
      <organization></organization> initials="R" surname="Verborgh">
              <organization/>
            </author>
            <author initials="" surname="Erik Mannens">
      <organization></organization> initials="E" surname="Mannens">
              <organization/>
            </author>
            <author initials="" surname="Rick Van initials="R" surname="Van de Walle">
      <organization></organization>
              <organization/>
            </author>
            <author initials="" surname="Thomas Steiner">
      <organization></organization> initials="T" surname="Steiner">
              <organization/>
            </author>
            <date year="2023" month="September" day="15"/>
          </front>
        </reference>

        <reference anchor="WebAPIext" target="https://webapi-discovery.github.io/rfcs/rfc0001.html">
          <front>
    <title>WebAPI
            <title>WADG0001 WebAPI type extension</title>
            <author initials="" surname="Mike Ralphson">
      <organization></organization> initials="M" surname="Ralphson" role="editor">
              <organization/>
            </author>
            <author initials="" surname="Nick Evans">
      <organization></organization> initials="N" surname="Evans" role="editor">
              <organization/>
            </author>
            <date year="2020" month="July" day="08"/>
          </front>
          <refcontent>Draft Community Group Report</refcontent>
        </reference>

<reference anchor="RFC8631">
  <front>
    <title>Link Relation Types for Web Services</title>
    <author fullname="E. Wilde" initials="E." surname="Wilde"/>
    <date month="July" year="2019"/>
    <abstract>
      <t>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.</t>
    </abstract>
  </front>
  <seriesInfo name="RFC" value="8631"/>
  <seriesInfo name="DOI" value="10.17487/RFC8631"/>
</reference>
        <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8631.xml"/>
      </references>
    </references>

<?line 568?>

    <section anchor="api-catalog-example-linkset"><name>Example anchor="api-catalog-example-linkset">
      <name>Example API catalog documents</name> Catalog Documents</name>
      <t>This section is informative and provides and example of an API
catalog document using the Linkset format.</t>
      <section anchor="api-catalog-example-rfc8615"><name>Using anchor="api-catalog-example-rfc8615">
<!-- [rfced] May we rephrase the following section title to avoid using RFC
8615 as an adjective?

Also, we have updated the RFC number to 8631 as we believe this was the
intended RFC.

Original:
   A.1.  Using Linkset with RFC8615 relations</name> relations

Perhaps:
   A.1.  Using Linkset with Link Relations Defined in RFC 8631
-->
        <name>Using Linkset with RFC 8631 Relations</name>
        <t>This example uses the Linkset format <xref target="RFC9264"/>, target="RFC9264"/> and the following
link relations defined in <xref target="RFC8631"/>:</t>

<t><list style="symbols">
  <t>"service-desc",
<!-- [rfced] We have updated the following bulleted list into a definition list
for a more cohesive presentation. Please let us know any objections.

Original:
   *  "service-desc", used to link to a description of the API that is
      primarily intended for machine consumption (for example the <xref target="OAS"></xref> [OAS]
      specification YAML or JSON file).</t>
  <t>"service-doc", 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 <eref target="https://datatracker.ietf.org/api/submission">Internet-Draft Internet-Draft submission API
instructions</eref>).</t>
  <t>"service-meta",
      instructions (https://datatracker.ietf.org/api/submission)).

   *  "service-meta", used to link to additional metadata about the API,
      and is primarily intended for machine consumption.</t>
  <t>"status", consumption.

   *  "status", used to link to the API status (e.g. API "health"
      indication etc.) for machine and/or human consumption.</t>
</list></t> consumption.

Current:
   "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 primarily
      intended for human consumption (an example of human-readable
      documentation is the IETF Internet-Draft submission API
      instructions (https://datatracker.ietf.org/api/submission)).

   "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.
-->
<dl spacing="normal">
   <dt>"service-desc":</dt><dd>Used to link to a description of the API that
   is primarily intended for machine consumption (for example, the <xref
   target="OAS"/> specification, YAML, or JSON file).</dd>
            <dt>"service-doc":</dt><dd>Used to link to API documentation that is primarily
intended for human consumption (an example of human-readable
documentation is the IETF <eref target="https://datatracker.ietf.org/api/submission" brackets="angle">Internet-Draft submission API
instructions</eref>).</dd>
            <dt>"service-meta":</dt><dd>Used to link to additional metadata about the API
and is primarily intended for machine consumption.</dd>
            <dt>"status":</dt><dd>Used to link to the API status (e.g., API "health"
indication) for machine and/or human consumption.</dd>
        </dl>
        <t>Client request:</t>

<figure><sourcecode
        <sourcecode type="http-message"><![CDATA[
GET .well-known/api-catalog HTTP/1.1
Host: example.com
Accept: application/linkset+json
]]></sourcecode></figure>
]]></sourcecode>
        <t>Server response:</t>

<figure><sourcecode
        <sourcecode type="http-message"><![CDATA[
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="THIS-RFC-URL"
]]></sourcecode></figure>

<figure><artwork><![CDATA[
    profile="https://www.rfc-editor.org/info/rfc9727"
]]></sourcecode>
        <sourcecode type=""><![CDATA[
{
  "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"
      }
    ]
  }
  ]
}
]]></artwork></figure>
]]></sourcecode>
      </section>
      <section anchor="api-catalog-example-linkset-bookmarks"><name>Using anchor="api-catalog-example-linkset-bookmarks">
        <name>Using Linkset with bookmarks</name> Bookmarks</name>
        <t>This example also uses the Linkset format <xref target="RFC9264"/>, listing target="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"
<xref target="RFC9264"/> link relation (to indicate they are an item in the
catalog). The intent is that by following a bookmark link, a
machine-client
machine client can discover the purpose and usage policy for each
API, hence
API; hence, the document targeted by the bookmark link should support
this.</t>
        <t>Client request:</t>

<figure><sourcecode
        <sourcecode type="http-message"><![CDATA[
GET .well-known/api-catalog HTTP/1.1
Host: example.com
Accept: application/linkset+json
]]></sourcecode></figure>
]]></sourcecode>
        <t>Server response:</t>

<figure><sourcecode
        <sourcecode type="http-message"><![CDATA[
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="THIS-RFC-URL"
]]></sourcecode></figure>

<figure><artwork><![CDATA[
    profile="https://www.rfc-editor.org/info/rfc9727"
]]></sourcecode>
        <sourcecode type=""><![CDATA[
{ "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"}
     ]
   }
 ]
}
]]></artwork></figure>
]]></sourcecode>
      </section>
      <section anchor="api-catalog-other-formats"><name>Other anchor="api-catalog-other-formats">
        <name>Other API catalog formats</name> Catalog Formats</name>
        <t>A non-exhaustive list of other API catalog document formats includes:</t>

<t><list style="symbols">
        <ul spacing="normal">
          <li>
            <t>An APIs.json document <xref target="APIsjson"></xref>.</t> target="APIsjson"/>.</t>
          </li>
          <li>
            <t>A RESTDesc semantic description for hypermedia APIs <xref target="RESTdesc"></xref>.</t> target="RESTdesc"/>.</t>
          </li>
          <li>
            <t>A Hypertext Application Language document <xref target="HAL"></xref>.</t> target="I-D.kelly-json-hal"/>.</t>
          </li>
          <li>
            <t>An extension to the Schema.org WebAPI type <xref target="WebAPIext"></xref>.</t>
</list></t> target="WebAPIext"/>.</t>
          </li>
        </ul>
      </section>
      <section anchor="api-catalog-example-linkset-nesting"><name>Nesting anchor="api-catalog-example-linkset-nesting">
        <name>Nesting API catalog links</name> Catalog Links</name>
        <t>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, APIs who wish to group
them in smaller catalogs (as described in <xref target="scalability"/>).</t>
        <t>Client request:</t>

<figure><sourcecode
        <sourcecode type="http-message"><![CDATA[
GET .well-known/api-catalog HTTP/1.1
Host: example.com
Accept: application/linkset+json
]]></sourcecode></figure>
]]></sourcecode>
        <t>Server response:</t>

<figure><sourcecode
        <sourcecode type="http-message"><![CDATA[
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="THIS-RFC-URL"
]]></sourcecode></figure>

<figure><artwork><![CDATA[
    profile="https://www.rfc-editor.org/info/rfc9727"
]]></sourcecode>
        <sourcecode type=""><![CDATA[
{
  "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"
        }
      ]
    }
  ]
}

]]></artwork></figure>
]]></sourcecode>
      </section>
    </section>
    <section anchor="acknowledgements"><name>Acknowledgements</name> anchor="acknowledgements" numbered="false">
      <name>Acknowledgements</name>
      <t>Thanks to 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 <contact fullname="Jan Algermissen"/>, <contact
      fullname="Phil Archer"/>, <contact fullname="Tim Bray"/>, <contact
      fullname="Ben Bucksch"/>, <contact fullname="Sanjay Dalal"/>, <contact
      fullname="David Dong"/>, <contact fullname="Erik Kline"/>, <contact
      fullname="Mallory Knodel"/>, <contact fullname="Murray Kucherawy"/>,
      <contact fullname="Max Maton"/>, <contact fullname="Darrel Miller"/>,
      <contact fullname="Mark Nottingham"/>, <contact fullname="Roberto
      Polli"/>, <contact fullname="Joey Salazar"/>, <contact fullname="Rich
      Salz"/>, <contact fullname="Herbert Van De Sompel, Orie Steele, Tina Tsou,
Gunter Sompel"/>, <contact
      fullname="Orie Steele"/>, <contact fullname="Tina Tsou"/>, <contact
      fullname="Gunter Van Der Velde, Eric Vyncke, and Erik Wilde de Velde"/>, <contact fullname="Éric Vyncke"/>,
      and <contact fullname="Erik Wilde"/> for their reviews,
suggestions suggestions, and
      support.</t>
    </section>
  </back>

<!-- ##markdown-source:
H4sIAAAAAAAAA+0923IbN5bvrOI/YOgHS1mSkpybw/FkRrGUWLEuHkmOK5VK
xSAJkj1qdnMa3ZIZleZb9lv2y/bcgAaaFzueZHcfdnZmLXU3gIODc79AvV6v
3SqTMjUD1dGLpDfSpU7z6UBpdWfStHeT5XeZen15onQ2VmmS3ajCpLpM8kyV
uZqZdKHGiR3lt6ZYqnyiDl+d2E67pYfDwtzCNPWcjQnbrXE+yvQcVh4XelL2
ElNOerOyXOCYYFxv/yl8q0v48P7o8Pr4AWYvjB6ok+Prb9st+MpM82I5ULYc
t1vtVrIoBqosKls+2d//av9Ju3Vjlnd5MR6oJCtNkZmyRyvix7aEff0Cy2Qw
/dJYeDLXRfnLP6u8NHagsrzdWiQD9VOZj7qw41GSjU1WdpXNi7IwEws/Lefy
Q1kkI3g1yucLLT/M4WN4lWSAOvMzrnhrssoM2i2lpkVeLQDv31RJOk6yqfom
zUc3Vk3yQr24vn7lcKlUuVzgAb3Jixv87jscSC/mOknhhWDtb4jCfl5M6Z0u
RjN5Zwd7e/gpPkpuTd99t4cP9oZFfmfNnkyyR4OnSTmrhjCcTuVu6g5mLzgY
+hBowdgyWKcxoM8z9ZM8HLq3/cj7s3KedhBbuipneYHo6uFqCjAJp/Kyr67m
MC8/YiJ6aW6TLHwM+9NZ8ivR6kD9kI/1BE6Z3xlG3A2O6Vsc87db+aAPp8Yf
VQUcvNvW3d1dP/6k3cryYg7T3/Jx4pEN1OW3z786ONjHB2+OT097L88v3pzT
46dfHHzOj7/pnZ6cvzw5/46fP3n6lOg2m0TzXRxeDRgQYdCLhcmAJNTVwoyS
STJiLvy0f9Df5++YSZ7sPzno7T/p8WowWhdTU9Y7sTC8n8NcgHBLVJBru8fn
yCNqpMN/eozyI10A46uzJE1NEb353hRmvlRvZgAl0G/07kwXdqa+0wXQd2PY
WXJj1KVOFzObZ9GbS9jVpS7zW3uzjF68LhJ1pYuE2FwRe/wDBsdYwqf9f/g5
PU72e/tfrcUJoAQxgUMIG3wK/tkv+/2DL/rluy24eQmEd6odbcnDq9LcGvUG
8DXPy5IhfnF4GgP7/dXFuXoB3F2U5l2pDheL1J0rTDit9NR86DbwaOErXRZ6
dGOKmsdBzO4hPwnP3YAUXvZwZ72ZTnsHB5v3RUf0Er/Hx/i/y+Or67Gxo3gX
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 [rfced] We note that the document uses single quotes (') and double
quotes (") inconsistently. For example, "api-catalog" and "example" appear
multiple times using both single and double quotes. Is this intentional?
If there are no objections, may we replace all instances of single quotes
with double quotes for consistency?
-->

<!-- [rfced] FYI - We have added expansions for the following abbreviations
per Section 3.6 of RFC 7322 ("RFC Style Guide"). Please review each
expansion in the document carefully to ensure correctness.

 Cross-Origin Resource Sharing (CORS)
 Fully Qualified Domain Name (FQDN)
 Top-Level Domain (TLD)
-->

<!-- [rfced] We updated artwork to sourcecode in Appendix A.1, A.2, and A.4 to
match the sourcecode element in Section 5.1. Please confirm that this is
correct.

Please consider whether the "type" attribute for these sourcecode
elements should be set to "json", "pseudocode", or something else.

The current list of preferred values for "type" is available at
<https://www.rfc-editor.org/rpc/wiki/doku.php?id=sourcecode-types>.
If the current list does not contain an applicable type, feel free to
suggest additions for consideration.

Note that it is also acceptable to leave the "type" attribute not set.
-->

<!-- [rfced] Please review the "Inclusive Language" portion of the online
Style Guide <https://www.rfc-editor.org/styleguide/part2/#inclusive_language>
and let us know if any changes are needed.  Updates of this nature typically
result in more precise language, which is helpful for readers.
Note that our script did not flag any words in particular, but this should
still be reviewed as a best practice. -->

</rfc>