rfc9727xml2.original.xml   rfc9727.xml 
<?xml version="1.0" encoding="UTF-8"?> <?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) -->
<!DOCTYPE rfc [ <!DOCTYPE rfc [
<!ENTITY nbsp "&#160;"> <!ENTITY nbsp "&#160;">
<!ENTITY zwsp "&#8203;"> <!ENTITY zwsp "&#8203;">
<!ENTITY nbhy "&#8209;"> <!ENTITY nbhy "&#8209;">
<!ENTITY wj "&#8288;"> <!ENTITY wj "&#8288;">
]> ]>
<?rfc tocindent="yes"?> <rfc xmlns:xi="http://www.w3.org/2001/XInclude" ipr="trust200902" submissionType
<?rfc strict="yes"?> ="IETF" docName="draft-ietf-httpapi-api-catalog-08" number="9727" category="std"
<?rfc compact="yes"?> consensus="true" tocInclude="true" sortRefs="true" symRefs="true" version="3" x
<?rfc comments="yes"?> ml:lang="en" updates="" obsoletes="">
<?rfc inline="yes"?>
<rfc ipr="trust200902" docName="draft-ietf-httpapi-api-catalog-08" category="std <!-- [rfced] FYI - We have updated the short title of the document,
" consensus="true" tocInclude="true" sortRefs="true" symRefs="true"> which appears in the running header in the PDF output, as follows.
<front> Please review and let us know any objections.
<title abbrev="api-catalog well-known URI">api-catalog: a well-known URI and
link relation to help discovery of APIs</title> Original:
api-catalog well-known URI
Current:
api-catalog: A Well-Known URI
-->
<front>
<title abbrev="api-catalog: A Well-Known URI">api-catalog: A Well-Known URI
and Link Relation to Help Discovery of APIs</title>
<seriesInfo name="RFC" value="9727"/>
<author initials="K." surname="Smith" fullname="Kevin Smith"> <author initials="K." surname="Smith" fullname="Kevin Smith">
<organization>Vodafone</organization> <organization>Vodafone</organization>
<address> <address>
<email>kevin.smith@vodafone.com</email> <email>kevin.smith@vodafone.com</email>
<uri>https://www.vodafone.com</uri> <uri>https://www.vodafone.com</uri>
</address> </address>
</author> </author>
<date month="June" year="2025"/>
<area>WIT</area>
<workgroup>httpapi</workgroup>
<date /> <!-- [rfced] Please insert any keywords (beyond those that appear in
the title) for use on https://www.rfc-editor.org/search. -->
<area>IETF</area>
<keyword>internet-draft</keyword> <keyword>example</keyword>
<abstract> <abstract>
<t>This document defines the "api-catalog" well-know URI and link
<?line 83?> relation. It is intended to facilitate automated discovery and usage of
published Application Programming Interfaces (APIs). A request to the
<t>This document defines the "api-catalog" well-known URI and link api-catalog resource will return a document providing information about,
relation. It is intended to facilitate automated discovery and and links to, the Publisher's APIs.</t>
usage of published APIs. A request to the api-catalog resource
will return a document providing information about, and links to,
the publisher's APIs.</t>
</abstract> </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/bro
wse/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> </front>
<middle> <middle>
<?line 91?> <section anchor="introduction">
<name>Introduction</name>
<section anchor="introduction"><name>Introduction</name> <t>An application may publish APIs
<t>An application may publish Application Programming Interfaces (APIs)
to encourage requests for interaction from external parties. Such to encourage requests for interaction from external parties. Such
APIs must be discovered before they may be used - i.e., the external APIs must be discovered before they may be used, i.e., the external
party needs to know what APIs a given publisher exposes, their party needs to know what APIs a given Publisher exposes, their
purpose, any policies for usage, and the endpoint to interact with purpose, any policies for usage, and the endpoint to interact with
each API. To facilitate automated discovery of this information, each API. To facilitate automated discovery of this information
and automated usage of the APIs, this document proposes:</t> and automated usage of the APIs, this document proposes:</t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>a well-known URI <xref target="WELL-KNOWN"/>, 'api-catalog', encoded as a U <t>a well-known URI <xref target="RFC8615"/>, 'api-catalog', that is e
RI ncoded as a URI
reference to an API catalog document describing a Publisher's API reference to an API catalog document describing a Publisher's API
endpoints.</t> endpoints.</t>
<t>a link relation <xref target="WEB-LINKING"/>, 'api-catalog', of which the t </li>
arget <li>
<t>a link relation <xref target="RFC8288"/>, 'api-catalog', of which t
he target
resource is the Publisher's API catalog document.</t> resource is the Publisher's API catalog document.</t>
</list></t> </li>
</ul>
<section anchor="goals">
<name>Goals and Non-Goals</name>
<!-- [rfced] Are the goals listed in Section 1.1 specified for api-catalog or
for this document?
<section anchor="goals"><name>Goals and non-goals</name> 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 <t>The primary goal is to facilitate the automated discovery of a
Publisher's public API endpoints, along with metadata that describes Publisher's public API endpoints, along with metadata that describes
the purpose and usage of each API, by specifying a well-known URI the purpose and usage of each API, by specifying a well-known URI
that returns an API catalog document. The API catalog document is that returns an API catalog document. The API catalog document is
primarily machine-readable to enable automated discovery and usage of primarily machine-readable to enable automated discovery and usage of
APIs, and it may also include links to human-readable documentation APIs, and it may also include links to human-readable documentation
(see the example in <xref target="api-catalog-example-rfc8615"/>).</t> (see the example in <xref target="api-catalog-example-rfc8615"/>).</t>
<t>Non-goals: This document does not mandate paths for API endpoints, i.
<t>Non-goals: this document does not mandate paths for API endpoints. e., it does not mandate that my_example_api's endpoint should be
i.e., it does not mandate that my_example_api's endpoint should be <tt>https://www.example.com/.well-known/api-catalog/my_example_api</tt>, nor
<spanx style="verb">https://www.example.com/.well-known/api-catalog/my_example_a
pi</spanx>, nor
even to be hosted at www.example.com (although it is not forbidden to even to be hosted at www.example.com (although it is not forbidden to
do so).</t> do so).</t>
</section>
</section> <section anchor="notational-conventions">
<section anchor="notational-conventions"><name>Notational Conventions</name> <name>Notational Conventions</name>
<t>The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECO
"MAY", and "OPTIONAL" in this document are to be interpreted as MMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
described in BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to be i
only when, they nterpreted as
described in BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and
only when, they
appear in all capitals, as shown here. appear in all capitals, as shown here.
These words may also appear in this document in These words may also appear in this document in
lower case as plain English words, absent their normative meanings. 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 targ
<t>The terms "content negotiation" and "status code" are from <xref target="HTTP et="RFC9110"/>.
"/>. The term "well-known URI" is from <xref target="RFC8615"/>.
The term "well-known URI" is from <xref target="WELL-KNOWN"/>. The term "link relation" is from <xref target="RFC8288"/>.</t>
The term "link relation" is from <xref target="WEB-LINKING"/>.</t> <t>The term "Publisher" refers to an organisation, company, or
individual that publishes one or more APIs for use by external third
parties. A fictional Publisher named "example" is used throughout
this document. The examples use the Fully Qualified Domain Names
(FQDNs) "www.example.com", "developer.example.com", "apis.example.com",
"apis.example.net", "gaming.example.com", and
"iot.example.net", where the .com and .net Top-Level Domains (TLDs) and
various
subdomains are simply used to illustrate that the "example" Publisher ma
y
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.
<t>The term "Publisher" refers to an organisation, company or individual Original:
that publishes one or more APIs for usage by external third parties. For scenarios
A fictional Publisher named "example" is used throughout this document. where the Publisher "example" is not the authority for a given
The examples use the FQDNs "www.example.com", "developer.example.com" _.example._ domain then that is made explicit in the text.
,"apis.example.com", "apis.example.net", "gaming.example.com",
"iot.example.net",where the use of the .com and .net TLDs and various
subdomains are simply to illustrate that the "example" Publisher may
have their API portfolio distributed across various domains for which
they are the authority. For scenarios where the Publisher "example"
is not the authority for a given <em>.example.</em> domain then that is made
explicit in the text.</t>
<t>In this document, "API" means the specification resources required 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" refers to the specification resources require
d
for an external party (or in the case of 'private' APIs, an internal for an external party (or in the case of 'private' APIs, an internal
party) to implement software which uses the Publisher's Application party) to implement software that uses the Publisher's API.</t>
Programming Interface.</t> <t>The specification recommends the use of TLS. Hence, "HTTPS" and
<t>The specification recommends the use of TLS, hence "HTTPS" and
"https://" are used throughout.</t> "https://" are used throughout.</t>
</section>
</section> </section>
</section> <section anchor="usage">
<section anchor="usage"><name>Using the 'api-catalog' well-known URI</name> <name>Using the 'api-catalog' Well-Known URI</name>
<t>The api-catalog well-known URI is intended for HTTPS servers that
<t>The api-catalog well-known URI is intended for HTTPS servers that
publish APIs.</t> publish APIs.</t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>The API catalog MUST be named "api-catalog" in a well-known location <t>The API catalog <bcp14>MUST</bcp14> be named "api-catalog" in a wel
as described by <xref target="WELL-KNOWN"/>.</t> l-known location
<t>The location of the API catalog document is decided by the Publisher: as described by <xref target="RFC8615"/>.</t>
the /.well-known/api-catalog URI provides a convenient reference to </li>
<li>
<t>The location of the API catalog document is decided by the Publishe
r.
The /.well-known/api-catalog URI provides a convenient reference to
that location.</t> that location.</t>
</list></t> </li>
</ul>
<t>A Publisher supporting this URI:</t> <t>A Publisher supporting this URI:</t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>SHALL resolve an HTTPS GET request to /.well-known/api-catalog and <t><bcp14>SHALL</bcp14> resolve an HTTPS GET request to /.well-known/a
return an API catalog document ( as described in <xref target="api-catalog"/> ). pi-catalog and
</t> return an API catalog document (as described in <xref target="api-catalog"/>).</
<t>SHALL resolve an HTTPS HEAD request to /.well-known/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 with a response including a Link header with the relation(s) defined
in <xref target="link-relation"/></t> in <xref target="link-relation"/>.</t>
</list></t> </li>
</ul>
</section> </section>
<section anchor="link-relation"><name>The api-catalog link relation</name> <section anchor="link-relation">
<name>The api-catalog Link Relation</name>
<t>This document introduces a new link relation <xref target="WEB-LINKING"/>, <t>This document introduces a new link relation <xref target="RFC8288"/>,
"api-catalog". This identifies a target resource that represents a "api-catalog". This identifies a target resource that represents a
list of APIs available from the Publisher of the link context. list of APIs available from the Publisher of the link context.
The target resource URI may be /.well-known/api-catalog , or any The target resource URI may be /.well-known/api-catalog or any
other URI chosen by the Publisher. For example, the Publisher other URI chosen by the Publisher. For example, the Publisher
'example' could include the api-catalog link relation in the HTTP 'example' could include the api-catalog link relation in the HTTP
header and/or content payload when responding to a request to header and/or content payload when responding to a request to
<spanx style="verb">https://www.example.com</spanx> :</t> <tt>https://www.example.com</tt>:</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8 Content-Type: text/html; charset=UTF-8
Location: /index.html Location: /index.html
Link: </my_api_catalog.json>; rel=api-catalog Link: </my_api_catalog.json>; rel=api-catalog
Content-Length: 356 Content-Length: 356
<!DOCTYPE HTML> <!DOCTYPE HTML>
<html> <html>
<head> <head>
<title>Welcome to Example Publisher</title> <title>Welcome to Example Publisher</title>
</head> </head>
<body> <body>
<p> <p>
<a href="my_api_catalog.json" rel="api-catalog"> <a href="my_api_catalog.json" rel="api-catalog">
Example Publisher's APIs Example Publisher's APIs
</a> </a>
</p> </p>
<p>(remainder of content)</p> <p>(remainder of content)</p>
</body> </body>
</html> </html>
]]></sourcecode>
<section anchor="using-additional-link-relations">
<name>Using Additional Link Relations</name>
]]></sourcecode></figure> <!-- [rfced] May we reformat the bulleted list items in Section 3.1 into
paragraph form?
<section anchor="using-additional-link-relations"><name>Using additional link re Original:
lations</name> 3.1. Using additional link relations
<t><list style="symbols"> * "item" [RFC6573]. When used in an API catalog document, the
<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.
* 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 docu
ment, the
"item" link relation identifies a target resource that represents an "item" link relation identifies a target resource that represents an
API that is a member of the API catalog.</t> API that is a member of the API catalog.</t>
<t>Other link relations may be utilised in an API catalog to convey </li>
<li>
<t>Other link relations may be utilised in an API catalog to convey
metadata descriptions for API links.</t> metadata descriptions for API links.</t>
</list></t> </li>
</ul>
</section>
</section>
<section anchor="api-catalog">
<name>The API 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?
</section> Original:
</section> As illustration, the API catalog document URI of
<section anchor="api-catalog"><name>The API catalog document</name> 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.
<t>The API catalog is a document listing a Publisher's APIs. The Perhaps:
Publisher may host the API catalog document at any URI(s) For example, the API catalog document URI of
they choose. As illustration, the API catalog document URI of https://www.example.com/my_api_catalog.json can be requested
<spanx style="verb">https://www.example.com/my_api_catalog.json</spanx> can be r directly or via a request to https://www.example.com/.well-known/
equested api-catalog, which the Publisher will resolve to
directly, or via a request to https://www.example.com/my_api_catalog.
<spanx style="verb">https://www.example.com/.well-known/api-catalog</spanx>, whi -->
ch the As illustration, the API catalog document URI of
Publisher will resolve to <spanx style="verb">https://www.example.com/my_api_cat <tt>https://www.example.com/my_api_catalog.json</tt> can be requested
alog</spanx>.</t> 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?
<section anchor="api-catalog-contents"><name>API catalog contents</name> 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.
<t>The API catalog MUST include hyperlinks to API endpoints, Perhaps:
and is RECOMMENDED to include useful metadata, such as usage 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 endpoin
ts,
and is <bcp14>RECOMMENDED</bcp14> to include useful metadata, such as usage
policies, API version information, links to the OpenAPI Specification policies, API version information, links to the OpenAPI Specification
<xref target="OAS"></xref> definitions for each API, etc. If the Publisher does not <xref target="OAS"/> definitions for each API, etc. If the Publisher does not
include that metadata directly in the API catalog document, they include that metadata directly in the API catalog document, they
SHOULD make that metadata available at the API endpoint URIs they <bcp14>SHOULD</bcp14> make that metadata available at the API endpoint URIs they
have listed (see <xref target="api-catalog-example-linkset-bookmarks"/> for have listed (see <xref target="api-catalog-example-linkset-bookmarks"/> for
an example).</t> an example).</t>
</section>
</section> <section anchor="api-catalog-formats">
<section anchor="api-catalog-formats"><name>API catalog formats</name> <name>API Catalog Formats</name>
<t>The Publisher <bcp14>MUST</bcp14> publish the API catalog document in
<t>The Publisher MUST publish the API catalog document in the Linkset the Linkset
format <spanx style="verb">application/linkset+json</spanx> (section 4.2 of <xre format <tt>application/linkset+json</tt> (<xref section="4.2" sectionFormat="of"
f target="RFC9264"/>). target="RFC9264"/>).
The Linkset SHOULD include a profile parameter (section 5 of The Linkset <bcp14>SHOULD</bcp14> include a profile parameter (<xref section="5"
<xref target="RFC9264"/>) with a Profile URI <xref target="RFC7284"/> value of ' sectionFormat="of" target="RFC9264"/>) with a Profile URI <xref target="RFC7284
THIS-RFC-URL' "/> value of 'https://www.rfc-editor.org/info/rfc9727'
to indicate the Linkset is representing an API catalog document as to indicate the Linkset is representing an API catalog document as
defined above. Appendix A includes example API catalog documents defined above. <xref target="api-catalog-example-linkset"/> includes example API catalog documents
based on the Linkset format.</t> based on the Linkset format.</t>
<t>The Publisher MAY make additional formats available via <!-- [rfced] FYI - We have updated the citation below since Section 5.3 of
content negotiation (section 5.3 of <xref target="HTTP"/>) to their [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 [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 vi
a
content negotiation (<xref section="12" sectionFormat="of" target="RFC9110"/>) t
o their
/.well-known/api-catalog location. A non-exhaustive list of such /.well-known/api-catalog location. A non-exhaustive list of such
formats that support the automated discovery, and machine (and formats that support the automated discovery and machine (and
human) usage of a Publisher's APIs, is listed at human) usage of a Publisher's APIs is listed at
<xref target="api-catalog-other-formats"/>. If a Publisher already lists their <xref target="api-catalog-other-formats"/>. If a Publisher already lists their
APIs in a format other than Linkset but wish to utilise the APIs in a format other than Linkset, but wishes to utilise the
/.well-known/api-catalog URI, then:</t> /.well-known/api-catalog URI, then:</t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>They MUST also implement a Linkset with, at minimum, hyperlinks to <t>They <bcp14>MUST</bcp14> also implement a Linkset with, at minimu
API endpoints - see the example of m, hyperlinks to
<xref target="api-catalog-example-linkset-bookmarks"/> in Appendix A.</t> API endpoints; see <xref target="api-catalog-example-linkset-bookmarks"/>.</t>
<t>They MAY support content negotiation at the </li>
/.well-known/api-catalog URI to allow their existing format to be <li>
returned.</t> <t>They <bcp14>MAY</bcp14> support content negotiation at the
</list></t> /.well-known/api-catalog URI to allow for the return of their existing format.</
t>
</section> </li>
<section anchor="nest"><name>Nesting API catalog links</name> </ul>
</section>
<t>An API catalog may itself contain links to other API catalogs, by <section anchor="nest">
using the 'api-catalog' relation type for each link. <name>Nesting API Catalog Links</name>
An example of this is given in <t>An API catalog may itself contain links to other API catalogs by usin
<xref target="api-catalog-example-linkset-nesting"/>.</t> g
the 'api-catalog' relation type for each link. An example of this is
</section> given in <xref target="api-catalog-example-linkset-nesting"/>.</t>
</section> </section>
<section anchor="operations"><name>Operational considerations</name> </section>
<section anchor="operations">
<section anchor="multiple_domains"><name>Accounting for APIs distributed across <name>Operational Considerations</name>
multiple domains</name> <section anchor="multiple_domains">
<name>Accounting for APIs Distributed Across Multiple Domains</name>
<t>A Publisher ("example") may have their APIs hosted across multiple <t>A Publisher ("example") may have their APIs hosted across multiple
domains that they manage: e.g., at <spanx style="verb">www.example.com</spanx>, domains that they manage, e.g., at <tt>www.example.com</tt>,
<spanx style="verb">developer.example.com</spanx>, <spanx style="verb">apis.exam <tt>developer.example.com</tt>, <tt>apis.example.com</tt>,
ple.com</spanx>, <tt>apis.example.net</tt>, etc. They may also use a third-party API
<spanx style="verb">apis.example.net</spanx> etc. They may also use a third-part hosting provider that hosts APIs on a distinct domain.</t>
y API <t>To account for this scenario, it is <bcp14>RECOMMENDED</bcp14> that:<
hosting provider which hosts APIs on a distinct domain.</t> /t>
<ul spacing="normal">
<t>To account for this scenario, it is RECOMMENDED that:</t> <li>
<t>The Publisher also publish the api-catalog well-known URI at each
<t><list style="symbols"> of their API domains, e.g., <tt>https://apis.example.com/.well-known/api-catalo
<t>The Publisher also publish the api-catalog well-known URI at each g</tt>,
of their API domains e.g. <tt>https://developer.example.net/.well-known/api-catalog</tt>, etc.</t>
<spanx style="verb">https://apis.example.com/.well-known/api-catalog</spanx>, </li>
<spanx style="verb">https://developer.example.net/.well-known/api-catalog</span <li>
x> etc.</t> <t>An HTTPS GET request to any of these URIs returns the same result
<t>An HTTPS GET request to any of these URIs returns the same result, ,
namely, the API catalog document.</t> namely, the API catalog document.</t>
<t>Since the physical location of the API catalog document is decided </li>
by the Publisher, and may change, the Publisher choose one of their <li>
<t>The Publisher choose one of their
instances of /.well-known/api-catalog as a canonical reference to instances of /.well-known/api-catalog as a canonical reference to
the location of the latest API catalog. The Publisher's other the location of the latest API catalog since the physical location of the API ca talog document is decided by the Publisher and may change. The Publisher's other
instances of /.well-known/api-catalog should redirect to this instances of /.well-known/api-catalog should redirect to this
canonical instance of /.well-known/api-catalog to ensure the latest canonical instance of /.well-known/api-catalog to ensure the latest
API catalog is returned.</t> API catalog is returned.</t>
</list></t> </li>
</ul>
<t>For example, if the Publisher's primary API portal is <t>For example, if the Publisher's primary API portal is
<spanx style="verb">https://apis.example.com</spanx>, then <tt>https://apis.example.com</tt>, then
<spanx style="verb">https://apis.example.com/.well-known/api-catalog</spanx> sho <tt>https://apis.example.com/.well-known/api-catalog</tt> should resolve to
uld resolve to
the location of the Publisher's latest API catalog document. If the 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>, Publisher is also the domain authority for <tt>www.example.net</tt>,
which also hosts a selection of their APIs, then a request to which also hosts a selection of their APIs, then a request to
<spanx style="verb">https://www.example.net/.well-known/api-catalog</spanx> shou <tt>https://www.example.net/.well-known/api-catalog</tt> should redirect
ld redirect to <tt>https://apis.example.com/.well-known/api-catalog</tt>.</t>
to <spanx style="verb">https://apis.example.com/.well-known/api-catalog</spanx>
.</t> <!-- [rfced] May we rephrase the following sentence for clarity?
Original:
If the Publisher is not the domain authority for 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 <t>If the Publisher is not the domain authority for
<spanx style="verb">www.example.net</spanx> - or any third-party domain that hos <tt>www.example.net</tt> -- or any third-party domain that hosts any
ts any of the Publisher's APIs -- then the Publisher <bcp14>MAY</bcp14> include a link
of the Publisher's APIs - then the Publisher MAY include a link in in
its own API catalog to that third-party domain's API catalog. its own API catalog to that third-party domain's API catalog.
For example, the API catalog available For example, the API catalog available
at <spanx style="verb">https://apis.example.com/.well-known/api-catalog</spanx>) at <tt>https://apis.example.com/.well-known/api-catalog</tt> may list APIs
may list APIs hosted at <tt>apis.example.com</tt> and also link to the API catalog hosted
hosted at <spanx style="verb">apis.example.com</spanx> and also link to the API at <tt>https://www.example.net/.well-known/api-catalog</tt> using the
catalog hosted
at <spanx style="verb">https://www.example.net/.well-known/api-catalog</spanx> u
sing the
"api-catalog" link relation:</t> "api-catalog" link relation:</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"linkset": [ "linkset": [
{ {
"anchor": "https://www.example.com/.well-known/api-catalog", "anchor": "https://www.example.com/.well-known/api-catalog",
"item": [ "item": [
{ {
"href": "https://developer.example.com/apis/foo_api" "href": "https://developer.example.com/apis/foo_api"
}, },
{ {
"href": "https://developer.example.com/apis/bar_api" "href": "https://developer.example.com/apis/bar_api"
}, },
{ {
"href": "https://developer.example.com/apis/cantona_api" "href": "https://developer.example.com/apis/cantona_api"
} }
], ],
"api-catalog": "https://www.example.net/.well-known/api-catalog" "api-catalog": "https://www.example.net/.well-known/api-catalog"
} }
] ]
} }
]]></sourcecode></figure> ]]></sourcecode>
</section>
</section> <section anchor="internal-use">
<section anchor="internal-use"><name>Internal use of api-catalog for private API <name>Internal Use of api-catalog for Private APIs</name>
s</name> <t>A Publisher may wish to use the api-catalog well-known URI on their
internal network to signpost authorised users (e.g., company
<t>A Publisher may wish to use the api-catalog well-known URI on their
internal network, to signpost authorised users (e.g. company
employees) towards internal/private APIs not intended for third-party employees) towards internal/private APIs not intended for third-party
use. This scenario may incur additional security considerations, as use. This scenario may incur additional security considerations as
noted in <xref target="security"/>.</t> noted in <xref target="security"/>.</t>
</section>
<section anchor="scalability">
<name>Scalability Guidelines</name>
<t>In cases where a Publisher has a large number of APIs potentially
deployed across multiple domains, two challenges may arise:</t>
<ul spacing="normal">
<li>
<t>Maintaining the catalog entries to ensure they are up to date and
correcting any errors.</t>
</li>
<li>
<t>Restricting the catalog size to help reduce network and
client-processing overheads.</t>
</li>
</ul>
<t>In both cases, a Publisher may benefit from grouping their APIs,
providing an API catalog document for each group and using the main
API catalog hosted at /.well-known/api-catalog to provide links to
these. For example, a Publisher may decide to group their APIs
according to a business category (e.g., 'gaming APIs', 'anti-fraud
APIs', etc.), a technology category (e.g., 'IOT', 'networks', 'AI',
etc.), or any other criterion.
</section> <!--[rfced] As this sentence reads awkwardly due to the two instances of
<section anchor="scalability"><name>Scalability guidelines</name> "already", may we remove the first one?
<t>In cases where a Publisher has a large number of APIs, potentially Original:
deployed across multiple domains, then two challenges may arise:</t> This grouping may already be implicit
where the Publisher has already published their APIs across multiple
domains, e.g. at gaming.example.com, iot.example.net, etc.
<t><list style="symbols"> Perhaps:
<t>Maintaining the catalog entries to ensure they are up to date and This grouping may be implicit
any errors corrected.</t> where the Publisher has already published their APIs across multiple
<t>Restricting the catalog size to help reduce network and domains, e.g., at gaming.example.com, iot.example.net, etc.
client-processing overheads.</t> -->
</list></t>
<t>In both cases a Publisher may benefit from grouping their APIs, This grouping may already be implicit
providing an API catalog document for each group - and use the main
API catalog hosted at /.well-known/api-catalog to provide links to
these. For example a Publisher may decide to group their APIs
according to a business category (e.g. 'gaming APIs', 'anti-fraud
APIs etc.) or a technology category (e.g. ''IOT', 'networks', 'AI'
etc.), or any other criterion. This grouping may already be implicit
where the Publisher has already published their APIs across multiple where the Publisher has already published their APIs across multiple
domains, e.g. at <spanx style="verb">gaming.example.com</spanx>, <spanx style="v domains, e.g., at <tt>gaming.example.com</tt>, <tt>iot.example.net</tt>, etc.</t
erb">iot.example.net</spanx>, etc.</t> >
<t><xref target="nest"/> shows how the API catalog at
<t><xref target="nest"/> shows how the API catalog at
/.well-known/api-catalog can use the api-catalog link relation to /.well-known/api-catalog can use the api-catalog link relation to
point to other API catalogs.</t> point to other API catalogs.</t>
<t>The Publisher <bcp14>SHOULD</bcp14> consider caching and compression
<t>The Publisher SHOULD consider caching and compression
techniques to reduce the network overhead of large API catalogs.</t> techniques to reduce the network overhead of large API catalogs.</t>
</section>
</section> <section anchor="maintenance">
<section anchor="maintenance"><name>Monitoring and maintenance</name> <name>Monitoring and Maintenance</name>
<t>Publishers are <bcp14>RECOMMENDED</bcp14> to follow operational best
<t>Publishers are RECOMMENDED to follow operational best practice when practice when
hosting API catalog(s), including but not limited to:</t> hosting API catalog(s), including, but not limited to:</t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>Availability. The Publisher should monitor availability of the API <t>Availability. The Publisher should monitor availability of the AP
catalog, and consider alternate means to resolve requests to I
catalog and consider alternate means to resolve requests to
/.well-known/api-catalog during planned downtime of hosts.</t> /.well-known/api-catalog during planned downtime of hosts.</t>
<t>Performance. Although the performance of APIs listed in an API </li>
<li>
<t>Performance. Although the performance of APIs listed in an API
catalog can demand high transactions per second and low-latency catalog can demand high transactions per second and low-latency
response, the retrieval of the API catalog itself to discover those response, the retrieval of the API catalog itself to discover those
APIs is less likely to incur strict performance demands. That said, APIs is less likely to incur strict performance demands. That said,
the Publisher should monitor the response time to fulfil a request the Publisher should monitor the response time to fulfil a request
for the API catalog, and determine any necessary improvements (as for the API catalog and determine any necessary improvements (as
with any other Web resource the Publisher serves). For large API with any other Web resource the Publisher serves). For large API
catalogs, the Publisher should consider the techniques described in catalogs, the Publisher should consider the techniques described in
<xref target="scalability"/>.</t> <xref target="scalability"/>.</t>
<t>Usage. Since the goal of the api-catalog well-known URI is to </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 facilitate discovery of APIs, the Publisher may wish to correlate
requests to the /.well-known/api-catalog URI with subsequent requests requests to the /.well-known/api-catalog URI with subsequent requests
to the API URIs listed in the catalog.</t> to the API URIs listed in the catalog.</t>
<t>Current data. The Publisher should include the removal of stale API </li>
<li>
<t>Current data. The Publisher should include the removal of stale A
PI
entries from the API catalog as part of their API release lifecycle. entries from the API catalog as part of their API release lifecycle.
The Publisher MAY decide to include metadata regarding legacy API The Publisher <bcp14>MAY</bcp14> decide to include metadata regarding legacy API
versions or deprecated APIs to help users of those APIs discover versions or deprecated APIs to help users of those APIs discover
up-to-date alternatives.</t> up-to-date alternatives.</t>
<t>Correct metadata. The Publisher should include human and/or </li>
<li>
<t>Correct metadata. The Publisher should include human and/or
automated checks for syntax errors in the API catalog. Automated automated checks for syntax errors in the API catalog. Automated
checks include format validation (e.g. to ensure valid JSON syntax) checks include format validation (e.g., to ensure valid JSON syntax)
and linting to enforce business rules - such as removing duplicate and linting to enforce business rules, such as removing duplicate
entries and ensuring descriptions are correctly named with valid entries and ensuring descriptions are correctly named with valid
values. A proofread of the API catalog as part of the API release values. A proofread of the API catalog as part of the API release
lifecycle is RECOMMENDED to detect any errors in business grammar lifecycle is <bcp14>RECOMMENDED</bcp14> to detect any errors in business grammar
(for example, an API entry that is described with valid syntax, but (for example, an API entry that is described with valid syntax, but
has been allocated an incorrect or outdated description.)</t> has been allocated an incorrect or outdated description.)</t>
<t>Security best practice, as set out in <xref target="security"/>.</t> </li>
</list></t> <li>
<t>Security best practice. See <xref target="security"/>.</t>
</section> </li>
<section anchor="integration"><name>Integration with existing API management fra </ul>
meworks</name> </section>
<section anchor="integration">
<t>A Publisher may already utilise an API management framework to <name>Integration with Existing API Management Frameworks</name>
<t>A Publisher may already utilise an API management framework to
produce their API portfolio. These frameworks typically include the produce their API portfolio. These frameworks typically include the
publication of API endpoint URIs, deprecation and redirection of publication of API endpoint URIs, deprecation and redirection of
legacy API versions, API usage policies and documentation, etc. legacy API versions, API usage policies and documentation, etc.
The api-catalog well-known URI and API catalog document are intended The api-catalog well-known URI and API catalog document are intended
to complement API management frameworks by facilitating the discovery to complement API management frameworks by facilitating the discovery
of the framework's outputs - API endpoints, usage policies and of the framework's outputs -- API endpoints, usage policies, and
documentation - and are not intended to replace any existing documentation -- and are not intended to replace any existing
API discovery mechanisms the framework has implemented.</t> API discovery mechanisms the framework has implemented.</t>
<t>Providers of such frameworks may include the production of an API
<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 catalog and the publication of the /.well-known/api-catalog URI as a
final pre-release (or post-release) step in the release management final pre-release (or post-release) step in the release management
workflow. The following steps are recommended:</t> workflow. The following steps are recommended.</t>
<t>If the /.well-known/api-catalog URI has not been published previously
<t>If the /.well-known/api-catalog URI has not been published previously , the framework provider should:</t>
, the framework provider should:</t> <ul spacing="normal">
<li>
<t><list style="symbols"> <t>Collate and check the metadata for each API that will be included
<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 in the API catalog. This metadata is likely to already exist in the
framework.</t> framework.</t>
<t>Determine which metadata to include in the API catalog, following </li>
<li>
<t>Determine which metadata to include in the API catalog following
the requirements set out in <xref target="api-catalog-contents"/> and the the requirements set out in <xref target="api-catalog-contents"/> and the
considerations set out in <xref target="operations"/>.</t> considerations set out in <xref target="operations"/>.</t>
<t>Map the chosen metadata to the format(s) described in </li>
<xref target="api-catalog-formats"/>. Where only the hyperlinks to APIs are to b <li>
e <t>Map the chosen metadata to the format(s) described in
included in the API catalog, then the structure suggested in <xref target="api-catalog-formats"/>. The structure suggested in
<xref target="api-catalog-example-linkset-bookmarks"/> may be followed. Where <xref target="api-catalog-example-linkset-bookmarks"/> may be followed where onl
possible the API catalog should include further metadata per the y the hyperlinks to APIs are to be
guidance in <xref target="api-catalog-contents"/>, in which case the structure included in the API catalog. Where
possible, the API catalog should include further metadata per the
guidance in <xref target="api-catalog-contents"/>; in which case, the structure
suggested in <xref target="api-catalog-example-linkset"/> can be utilised and suggested in <xref target="api-catalog-example-linkset"/> can be utilised and
adapted (ensuring compliance to <xref target="RFC9264"/>) to reflect the nature adapted (ensuring compliance to <xref target="RFC9264"/>) to reflect the nature
of the chosen metadata.</t> of the chosen metadata.</t>
<t>Publish the /.well-known/api-catalog URI following the guidance set </li>
<li>
<t>Publish the /.well-known/api-catalog URI following the guidance s
et
out in <xref target="usage"/>.</t> out in <xref target="usage"/>.</t>
</list></t> </li>
</ul>
<t>If the /.well-known/api-catalog URI has previously been published, <t>If the /.well-known/api-catalog URI has previously been published,
the framework provider should:</t> the framework provider should:</t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>Include a step in the release management lifecycle to refresh the <t>Include a step in the release management lifecycle to refresh the
API catalog following any changes in API hyperlinks or published API catalog following any changes in API hyperlinks or published
metadata. This could include placing triggers on certain metadata metadata. This could include placing triggers on certain metadata
fields, so that as they are updated in pre-production on the API 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 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 catalog to be pushed live when the release is published by the
framework.</t> framework.</t>
</list></t> </li>
</ul>
</section> </section>
</section> </section>
<section anchor="conform-rfc8615"><name>Conformance to RFC8615</name> <section anchor="conform-rfc8615">
<name>Conformance to RFC 8615</name>
<t>The requirements in section 3 of <xref target="WELL-KNOWN"/> for defining <t>The requirements in <xref section="3" sectionFormat="of" target="RFC861
Well-Known Uniform Resource Identifiers are met as described in the 5"/> for defining
following sub-sections.</t> Well-Known URIs are met as described in the
following subsections.</t>
<section anchor="path-suffix"><name>Path suffix</name> <section anchor="path-suffix">
<name>Path Suffix</name>
<t>The api-catalog URI SHALL be appended to the /.well-known/ <t>The api-catalog URI <bcp14>SHALL</bcp14> be appended to the /.well-kn
own/
path-prefix for "well-known locations".</t> path-prefix for "well-known locations".</t>
</section>
</section> <section anchor="formats-and-associated-media-types">
<section anchor="formats-and-associated-media-types"><name>Formats and associate <name>Formats and Associated Media Types</name>
d media types</name> <t>A /.well-known/api-catalog location <bcp14>MUST</bcp14> support the L
inkset
<t>A /.well-known/api-catalog location MUST support the Linkset <xref target="RFC9264"/> format of application/linkset+json and <bcp14>MAY</bcp1
<xref target="RFC9264"/> format of application/linkset+json, and MAY 4>
also support the other formats via content negotiation.</t> also support the other formats via content negotiation.</t>
</section>
</section> <!-- [rfced] We note that Section 6.3 is titled "Registration of the
<section anchor="registration-of-the-api-catalog-well-known-uri"><name>Registrat api-catalog Well-Known URI" and simply states "See Section 7 considerations
ion of the api-catalog well-known URI</name> 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
<t>See <xref target="iana"/> considerations below.</t> section to avoid repetition? -->
</section>
</section>
<section anchor="iana"><name>IANA Considerations</name>
<section anchor="the-api-catalog-well-known-uri"><name>The api-catalog well-know
n URI</name>
<t>This specification registers the "api-catalog" well-known URI in the
Well-Known URI 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>
</section>
<section anchor="the-api-catalog-link-relation"><name>The api-catalog link relat
ion</name>
<t>This specification registers the "api-catalog" link relation 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 to a list of APIs available from the publisher
of the link context.</t>
<t>Reference: THIS-RFC</t>
</list></t>
</section>
<section anchor="the-api-catalog-profile-uri"><name>The api-catalog Profile URI<
/name>
<t>This specification registers "THIS-RFC-URL" 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 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>
</section> <section anchor="registration-of-the-api-catalog-well-known-uri">
</section> <name>Registration of the api-catalog Well-Known URI</name>
<section anchor="security"><name>Security Considerations</name> <t>See <xref target="iana"/> considerations below.</t>
</section>
</section>
<section anchor="iana">
<name>IANA Considerations</name>
<section anchor="the-api-catalog-well-known-uri">
<name>The api-catalog Well-Known URI</name>
<t>This specification registers the "api-catalog" well-known URI in
the "Well-Known URIs" registry as defined by <xref
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 api-catalog Link Relation</name>
<t>This specification registers the "api-catalog" link relation in the "
Link Relation Types" registry by
following the procedures per <xref 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 of the link context.</dd>
<dt>Reference:</dt><dd>RFC 9727</dd>
</dl>
</section>
<t>For all scenarios:</t> <!-- [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.
-->
<t><list style="symbols"> <section anchor="the-api-catalog-profile-uri">
<t>TLS SHOULD be used, i.e. make /.well-known/api-catalog available <name>The api-catalog Profile URI</name>
exclusively over HTTPS, to ensure no tampering of the API catalog</t> <t>This specification registers "https://www.rfc-editor.org/info/rfc9727
<t>The Publisher SHOULD take into account the Security Considerations " in the "Profile URIs"
from section 4 of <xref target="WELL-KNOWN"/>.</t> registry according to <xref target="RFC7284"/>.</t>
<t>The Publisher SHOULD perform a security and privacy review of the <dl spacing="compact" newline="false">
API catalog prior to deployment, to ensure it does not leak personal, <dt>Profile URI:</dt><dd>https://www.rfc-editor.org/info/rfc9727</dd>
business or other sensitive metadata, nor expose any vulnerability <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.</dd>
<dt>Reference:</dt><dd>RFC 9727</dd>
</dl>
</section>
</section>
<section anchor="security">
<name>Security Considerations</name>
<t>For all scenarios:</t>
<ul spacing="normal">
<li>
<t>TLS <bcp14>SHOULD</bcp14> be used, i.e., make /.well-known/api-cata
log available
exclusively over HTTPS, to ensure no tampering of the API catalog.</t>
</li>
<li>
<t>The Publisher <bcp14>SHOULD</bcp14> take into account the security
considerations
from <xref section="4" sectionFormat="of" target="RFC8615"/>.</t>
</li>
<li>
<t>The Publisher <bcp14>SHOULD</bcp14> perform a security and privacy
review of the
API catalog prior to deployment to ensure it does not leak personal,
business, or other sensitive metadata, nor expose any vulnerability
related to the APIs listed.</t> related to the APIs listed.</t>
<t>The Publisher SHOULD enforce read-only privileges for external </li>
requests to .well-known/api-catalog, and for internal systems and <li>
<t>The Publisher <bcp14>SHOULD</bcp14> enforce read-only privileges fo
r external
requests to .well-known/api-catalog and for internal systems and
roles that monitor the .well-known/api-catalog URI. Write privileges roles that monitor the .well-known/api-catalog URI. Write privileges
SHOULD only be granted to roles that perform updates to the API <bcp14>SHOULD</bcp14> only be granted to roles that perform updates to the API
catalog and/or the forwarding rewrite rules for the catalog and/or the forwarding rewrite rules for the
.well-known/api-catalog URI.</t> .well-known/api-catalog URI.</t>
<t>As with any Web offering, it is RECOMMENDED to apply rate-limiting </li>
measures to help mitigate abuse and prevent Denial-of-Service <li>
<t>As with any Web offering, it is <bcp14>RECOMMENDED</bcp14> to apply
rate-limiting
measures to help mitigate abuse and prevent denial-of-service
attacks on the API catalog endpoint.</t> attacks on the API catalog endpoint.</t>
</list></t> </li>
</ul>
<t>For the public-facing APIs scenario: security teams SHOULD <t>For the public-facing APIs scenario, security teams <bcp14>SHOULD</bcp1
4>
additionally audit the API catalog to ensure no APIs intended solely additionally audit the API catalog to ensure no APIs intended solely
for internal use have been mistakenly included. For example, a for internal use have been mistakenly included. For example, a
catalog hosted on <spanx style="verb">https://developer.example.com</spanx> shou ld not expose catalog hosted on <tt>https://developer.example.com</tt> should not expose
unnecessary metadata about any internal domains 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, the Publisher <bcp14>SHOULD</bc
<t>For the internal/private APIs scenario: the Publisher SHOULD take p14> take
steps to ensure that appropriate controls - such as CORS policies and steps to ensure that appropriate controls, such as Cross-Origin Resource Sharing
access control lists - are in place to ensure only authorised roles (CORS) policies and
access control lists, are in place to ensure only authorised roles
and systems may access an internal api-catalog well-known URI.</t> and systems may access an internal api-catalog well-known URI.</t>
<t>A comprehensive API catalog that is regularly audited may assist
<t>A comprehensive API catalog that is regularly audited may assist the Publisher in decommissioning 'zombie' APIs, i.e., legacy/obsolete
the Publisher in decommissioning 'zombie' APIs i.e., legacy/obsolete
APIs that should no longer be available. Such APIs represent a APIs that should no longer be available. Such APIs represent a
security vulnerability as they are unlikely to be supported, security vulnerability as they are unlikely to be supported,
monitored, patched or updated.</t> monitored, patched, or updated.</t>
<t>Note the registration of domain names and associated policies is out
<t>Note the registration of domain names and associated policies is out
of scope of this document.</t> 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 anchor="sec-normative-references">
<name>Normative References</name>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9
110.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
615.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
288.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2
119.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
174.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
573.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9
264.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7
284.xml"/>
</references>
<references anchor="sec-informative-references">
<name>Informative References</name>
</section> <!-- [rfced] Please review the following reference. The URL uses the "latest
published version", which now takes the reader to version 3.1.1 of [OAS]
rather than version 3.1.0 (please note that there has also been a change
of authors between versions). Please clarify if you wish for this
reference to point to one of these specific versions. If you would like
to refer to the latest version, we recommend the following format (with
an added annotation).
</middle> 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>.
<back> 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.htm
l>.
Latest version available at <https://spec.openapis.org/oas/latest.h
tml>.
-->
<references title='Normative References' anchor="sec-normative-references"> <!-- RE note: XML for updated reference to [OAS]
<reference anchor="OAS" target="https://spec.openapis.org/oas/latest">
<front>
<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 initials="R" surname="Ratovsky" role="editor">
<organization/>
</author>
<date year="2024" month="October" day="24/>
</front>
<annotation>Latest version available at <eref
target="https://spec.openapis.org/oas/latest.html" brackets="angle"/>.
</annotation>
</reference>
-->
<reference anchor="OAS" target="https://spec.openapis.org/oas/latest">
<front>
<title>OpenAPI Specification v3.1.0</title>
<author initials="D" surname="Miller" role="editor">
<organization/>
</author>
<author initials="J" surname="Whitlock" role="editor">
<organization/>
</author>
<author initials="M" surname="Gardiner" role="editor">
<organization/>
</author>
<author initials="M" surname="Ralphson" role="editor">
<organization/>
</author>
<author initials="R" surname="Ratovsky" role="editor">
<organization/>
</author>
<author initials="U" surname="Sarid" role="editor">
<organization/>
</author>
<date year="2021" month="February" day="15"/>
</front>
</reference>
<reference anchor="HTTP"> <!-- [rfced] Please review the following reference. The date provided for this
<front> reference is 15 September 2020, but the URL lists a date of
<title>HTTP Semantics</title> 9 January 2020. We have updated this reference to use that date.
<author fullname="R. Fielding" initials="R." role="editor" surname="Fielding
"/>
<author fullname="M. Nottingham" initials="M." role="editor" surname="Nottin
gham"/>
<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 do
cument describes the overall architecture of HTTP, establishes common terminolog
y, and defines aspects of the protocol that are shared by all versions. In this
definition are core protocol elements, extensibility mechanisms, and the "http"
and "https" Uniform Resource Identifier (URI) schemes.</t>
<t>This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 723
3, 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-kno
wn/", in selected Uniform Resource Identifier (URI) schemes.</t>
<t>In doing so, it obsoletes RFC 5785 and updates the URI schemes defined
in RFC 7230 to reserve that space. It also updates RFC 7595 to track URI schemes
that support well-known URIs in their registry.</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 a model for the relationships between resour
ces on the Web ("links") and the type of those relationships ("link relation typ
es").</t>
<t>It also defines the serialisation of such links in HTTP headers with th
e 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 for use in RFCs 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 to signify the
requirements in the specification. These words are often capitalized. This docu
ment defines these words as they should be interpreted in IETF documents. This d
ocument 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 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 specif
ications. This document aims to reduce the ambiguity by clarifying that only UPP
ERCASE 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 r
esources on the Web. This specification defines a pair of reciprocal link relati
on types that may be used to express the relationship between a collection and i
ts members. This document is not an Internet Standards Track specification; it i
s 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 r
epresenting sets of links as standalone documents. One format is based on JSON,
and the other is aligned with the format for representing links in the HTTP "Lin
k" header field. This specification also introduces a link relation type to supp
ort the discovery of sets of links.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="9264"/>
<seriesInfo name="DOI" value="10.17487/RFC9264"/>
</reference>
<reference anchor="RFC7284">
<front>
<title>The Profile URI Registry</title>
<author fullname="M. Lanthaler" initials="M." surname="Lanthaler"/>
<date month="June" year="2014"/>
<abstract>
<t>This document defines a registry for profile URIs to be used in specifi
cations standardizing profiles.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="7284"/>
<seriesInfo name="DOI" value="10.17487/RFC7284"/>
</reference>
</references> 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?
<references title='Informative References' anchor="sec-informative-reference Current:
s"> [APIsjson] Lane, K. and S. Willmott, "API Discovery Format", 9
January 2020,
<http://apisjson.org/format/apisjson_0.16.txt>.
<reference anchor="OAS" target="https://spec.openapis.org/oas/latest"> Perhaps:
<front> [APIsjson] Lane, K. and S. Willmott, "API Discovery Format", 6
<title>OpenAPI Specification 3.1.0</title> November 2024, <https://apisjson.org/format/apisjson_0.19.txt>.
<author initials="" surname="Darrel Miller"> Latest version available at <https://apisjson.org/>.
<organization></organization> -->
</author>
<author initials="" surname="Jeremy Whitlock">
<organization></organization>
</author>
<author initials="" surname="Marsh Gardiner">
<organization></organization>
</author>
<author initials="" surname="Mike Ralphson">
<organization></organization>
</author>
<author initials="" surname="Ron Ratovsky">
<organization></organization>
</author>
<author initials="" surname="Uri Sarid">
<organization></organization>
</author>
<date year="2021" month="February" day="15"/>
</front>
</reference>
<reference anchor="APIsjson" target="http://apisjson.org/format/apisjson_0.16.tx
t">
<front>
<title>APIs.json</title>
<author initials="" surname="Kin Lane">
<organization></organization>
</author>
<author initials="" surname="Steve Willmott">
<organization></organization>
</author>
<date year="2020" month="September" day="15"/>
</front>
</reference>
<reference anchor="HAL" target="https://datatracker.ietf.org/doc/html/draft-kell
y-json-hal-11">
<front>
<title>JSON Hypertext Application Language</title>
<author initials="" surname="Mike Kelly">
<organization></organization>
</author>
<date year="2020" month="September" day="15"/>
</front>
</reference>
<reference anchor="RESTdesc" target="http://apisjson.org/format/apisjson_0.16.tx
t">
<front>
<title>RESTdesc</title>
<author initials="" surname="Ruben Verborgh">
<organization></organization>
</author>
<author initials="" surname="Erik Mannens">
<organization></organization>
</author>
<author initials="" surname="Rick Van de Walle">
<organization></organization>
</author>
<author initials="" surname="Thomas Steiner">
<organization></organization>
</author>
<date year="2023" month="September" day="15"/>
</front>
</reference>
<reference anchor="WebAPIext" target="https://webapi-discovery.github.io/rfcs/rf
c0001.html">
<front>
<title>WebAPI type extension</title>
<author initials="" surname="Mike Ralphson">
<organization></organization>
</author>
<author initials="" surname="Nick Evans">
<organization></organization>
</author>
<date year="2020" month="July" day="08"/>
</front>
</reference>
<reference anchor="RFC8631"> <!-- RE note: XML for updated reference to [APIsjson]
<front> <reference anchor="APIsjson" target="https://apisjson.org/format/apisjso
<title>Link Relation Types for Web Services</title> n_0.19.txt">
<author fullname="E. Wilde" initials="E." surname="Wilde"/> <front>
<date month="July" year="2019"/> <title>API Discovery Format</title>
<abstract> <author initials="K" surname="Lane">
<t>Many resources provided on the Web are part of sets of resources that a <organization/>
re provided in a context that is managed by one particular service provider. Oft </author>
en, these sets of resources are referred to as "Web services" or "Web APIs". Thi <author initials="S" surname="Willmott">
s specification defines link relations that represent relationships from Web ser <organization/>
vices or APIs to resources that provide documentation, descriptions, metadata, o </author>
r status information for these resources. Documentation is primarily intended fo <date year="2024" month="November" day="6"/>
r human consumers, whereas descriptions are primarily intended for automated con </front>
sumers. Metadata provides information about a service's context. This specificat <annotation>Latest version available at <eref
ion also defines a link relation to identify status resources that are used to r target="https://apisjson.org/"
epresent information about service status.</t> brackets="angle"/>.</annotation>
</abstract> </reference>
</front> -->
<seriesInfo name="RFC" value="8631"/>
<seriesInfo name="DOI" value="10.17487/RFC8631"/>
</reference>
</references> <reference anchor="APIsjson" target="http://apisjson.org/format/apisjson
_0.16.txt">
<front>
<title>API Discovery Format</title>
<author initials="K" surname="Lane">
<organization/>
</author>
<author initials="S" surname="Willmott">
<organization/>
</author>
<date year="2020" month="January" day="9"/>
</front>
</reference>
<?line 568?> <!-- IESG State: Expired as of 02/05/25 -->
<xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.
kelly-json-hal.xml"/>
<section anchor="api-catalog-example-linkset"><name>Example API catalog document <!-- [rfced] Please review the reference entry for [RESTdesc]. It uses the
s</name> same URL as [APIsjson] (https://apisjson.org/format/apisjson_0.16.txt).
<t>This section is informative and provides and example of an API 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="R" surname="Verborgh">
<organization/>
</author>
<author initials="E" surname="Mannens">
<organization/>
</author>
<author initials="R" surname="Van de Walle">
<organization/>
</author>
<author 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>WADG0001 WebAPI type extension</title>
<author initials="M" surname="Ralphson" role="editor">
<organization/>
</author>
<author initials="N" surname="Evans" role="editor">
<organization/>
</author>
<date year="2020" month="July" day="08"/>
</front>
<refcontent>Draft Community Group Report</refcontent>
</reference>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
631.xml"/>
</references>
</references>
<section anchor="api-catalog-example-linkset">
<name>Example API Catalog Documents</name>
<t>This section is informative and provides and example of an API
catalog document using the Linkset format.</t> catalog document using the Linkset format.</t>
<section anchor="api-catalog-example-rfc8615">
<!-- [rfced] May we rephrase the following section title to avoid using RFC
8615 as an adjective?
<section anchor="api-catalog-example-rfc8615"><name>Using Linkset with RFC8615 r Also, we have updated the RFC number to 8631 as we believe this was the
elations</name> intended RFC.
<t>This example uses the Linkset format <xref target="RFC9264"/>, and the follow Original:
ing A.1. Using Linkset with RFC8615 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"/> and the
following
link relations defined in <xref target="RFC8631"/>:</t> link relations defined in <xref target="RFC8631"/>:</t>
<!-- [rfced] We have updated the following bulleted list into a definition list
for a more cohesive presentation. Please let us know any objections.
<t><list style="symbols"> Original:
<t>"service-desc", used to link to a description of the API that is * "service-desc", used to link to a description of the API that is
primarily intended for machine consumption (for example the <xref target="OAS">< primarily intended for machine consumption (for example the [OAS]
/xref> specification YAML or JSON file).
specification YAML or JSON file).</t>
<t>"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/submiss
ion">Internet-Draft submission API
instructions</eref>).</t>
<t>"service-meta", used to link to additional metadata about the API,
and is primarily intended for machine consumption.</t>
<t>"status", used to link to the API status (e.g. API "health"
indication etc.) for machine and/or human consumption.</t>
</list></t>
<t>Client request:</t> * "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)).
<figure><sourcecode type="http-message"><![CDATA[ * "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 etc.) for machine and/or human 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/submiss
ion" brackets="angle">Internet-Draft submission API
instructions</eref>).</dd>
<dt>"service-meta":</dt><dd>Used to link to additional metadata abou
t the API
and is primarily intended for machine consumption.</dd>
<dt>"status":</dt><dd>Used to link to the API status (e.g., API "hea
lth"
indication) for machine and/or human consumption.</dd>
</dl>
<t>Client request:</t>
<sourcecode type="http-message"><![CDATA[
GET .well-known/api-catalog HTTP/1.1 GET .well-known/api-catalog HTTP/1.1
Host: example.com Host: example.com
Accept: application/linkset+json Accept: application/linkset+json
]]></sourcecode></figure> ]]></sourcecode>
<t>Server response:</t>
<t>Server response:</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 01 Jun 2023 00:00:01 GMT Date: Mon, 01 Jun 2023 00:00:01 GMT
Server: Apache-Coyote/1.1 Server: Apache-Coyote/1.1
Content-Type: application/linkset+json; Content-Type: application/linkset+json;
profile="THIS-RFC-URL" profile="https://www.rfc-editor.org/info/rfc9727"
]]></sourcecode></figure> ]]></sourcecode>
<sourcecode type=""><![CDATA[
<figure><artwork><![CDATA[
{ {
"linkset": [ "linkset": [
{ {
"anchor": "https://developer.example.com/apis/foo_api", "anchor": "https://developer.example.com/apis/foo_api",
"service-desc": [ "service-desc": [
{ {
"href": "https://developer.example.com/apis/foo_api/spec", "href": "https://developer.example.com/apis/foo_api/spec",
"type": "application/yaml" "type": "application/yaml"
} }
], ],
skipping to change at line 915 skipping to change at line 1080
], ],
"service-doc": [ "service-doc": [
{ {
"href": "https://apis.example.net/apis/cantona_api/doc", "href": "https://apis.example.net/apis/cantona_api/doc",
"type": "text/html" "type": "text/html"
} }
] ]
} }
] ]
} }
]]></artwork></figure> ]]></sourcecode>
</section>
</section> <section anchor="api-catalog-example-linkset-bookmarks">
<section anchor="api-catalog-example-linkset-bookmarks"><name>Using Linkset with <name>Using Linkset with Bookmarks</name>
bookmarks</name> <t>This example also uses the Linkset format <xref target="RFC9264"/> an
d lists the
<t>This example also uses the Linkset format <xref target="RFC9264"/>, listing t
he
API endpoints in an array of bookmarks. Each link shares the same API endpoints in an array of bookmarks. Each link shares the same
context anchor (the well-known URI of the API catalog) and "item" 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 <xref target="RFC9264"/> link relation (to indicate they are an item in the
catalog). The intent is that by following a bookmark link, a catalog). The intent is that by following a bookmark link, a
machine-client can discover the purpose and usage policy for each machine client can discover the purpose and usage policy for each
API, hence the document targeted by the bookmark link should support API; hence, the document targeted by the bookmark link should support
this.</t> this.</t>
<t>Client request:</t>
<t>Client request:</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
GET .well-known/api-catalog HTTP/1.1 GET .well-known/api-catalog HTTP/1.1
Host: example.com Host: example.com
Accept: application/linkset+json Accept: application/linkset+json
]]></sourcecode></figure> ]]></sourcecode>
<t>Server response:</t>
<t>Server response:</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 01 Jun 2023 00:00:01 GMT Date: Mon, 01 Jun 2023 00:00:01 GMT
Server: Apache-Coyote/1.1 Server: Apache-Coyote/1.1
Content-Type: application/linkset+json; Content-Type: application/linkset+json;
profile="THIS-RFC-URL" profile="https://www.rfc-editor.org/info/rfc9727"
]]></sourcecode></figure> ]]></sourcecode>
<sourcecode type=""><![CDATA[
<figure><artwork><![CDATA[
{ "linkset": { "linkset":
[ [
{ "anchor": "https://www.example.com/.well-known/api-catalog", { "anchor": "https://www.example.com/.well-known/api-catalog",
"item": [ "item": [
{"href": "https://developer.example.com/apis/foo_api"}, {"href": "https://developer.example.com/apis/foo_api"},
{"href": "https://developer.example.com/apis/bar_api"}, {"href": "https://developer.example.com/apis/bar_api"},
{"href": "https://developer.example.com/apis/cantona_api"} {"href": "https://developer.example.com/apis/cantona_api"}
] ]
} }
] ]
} }
]]></artwork></figure> ]]></sourcecode>
</section>
</section> <section anchor="api-catalog-other-formats">
<section anchor="api-catalog-other-formats"><name>Other API catalog formats</nam <name>Other API Catalog Formats</name>
e> <t>A non-exhaustive list of other API catalog document formats includes:
</t>
<t>A non-exhaustive list of other API catalog document formats includes:</t> <ul spacing="normal">
<li>
<t><list style="symbols"> <t>An APIs.json document <xref target="APIsjson"/>.</t>
<t>An APIs.json document <xref target="APIsjson"></xref>.</t> </li>
<t>A RESTDesc semantic description for hypermedia APIs <xref target="RESTdesc" <li>
></xref>.</t> <t>A RESTDesc semantic description for hypermedia APIs <xref target=
<t>A Hypertext Application Language document <xref target="HAL"></xref>.</t> "RESTdesc"/>.</t>
<t>An extension to the Schema.org WebAPI type <xref target="WebAPIext"></xref> </li>
.</t> <li>
</list></t> <t>A Hypertext Application Language document <xref target="I-D.kelly
-json-hal"/>.</t>
</section> </li>
<section anchor="api-catalog-example-linkset-nesting"><name>Nesting API catalog <li>
links</name> <t>An extension to the Schema.org WebAPI type <xref target="WebAPIex
t"/>.</t>
<t>In this example, a request to the /.well-known/api-catalog URI </li>
</ul>
</section>
<section anchor="api-catalog-example-linkset-nesting">
<name>Nesting API 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 returns an array of links of relation type 'api-catalog'. This can be
useful to Publishers with a large number of APIs, who wish to group useful to Publishers with a large number of APIs who wish to group
them in smaller catalogs (as described in <xref target="scalability"/>).</t> them in smaller catalogs (as described in <xref target="scalability"/>).</t>
<t>Client request:</t>
<t>Client request:</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
GET .well-known/api-catalog HTTP/1.1 GET .well-known/api-catalog HTTP/1.1
Host: example.com Host: example.com
Accept: application/linkset+json Accept: application/linkset+json
]]></sourcecode></figure> ]]></sourcecode>
<t>Server response:</t>
<t>Server response:</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 01 Jun 2023 00:00:01 GMT Date: Mon, 01 Jun 2023 00:00:01 GMT
Server: Apache-Coyote/1.1 Server: Apache-Coyote/1.1
Content-Type: application/linkset+json; Content-Type: application/linkset+json;
profile="THIS-RFC-URL" profile="https://www.rfc-editor.org/info/rfc9727"
]]></sourcecode></figure> ]]></sourcecode>
<sourcecode type=""><![CDATA[
<figure><artwork><![CDATA[
{ {
"linkset": [ "linkset": [
{ {
"anchor": "https://www.example.com/.well-known/api-catalog", "anchor": "https://www.example.com/.well-known/api-catalog",
"api-catalog": [ "api-catalog": [
{ {
"href": "https://apis.example.com/iot/api-catalog" "href": "https://apis.example.com/iot/api-catalog"
}, },
{ {
"href": "https://ecommerce.example.com/api-catalog" "href": "https://ecommerce.example.com/api-catalog"
}, },
{ {
"href": "https://developer.example.com/gaming/api-catalog" "href": "https://developer.example.com/gaming/api-catalog"
} }
] ]
} }
] ]
} }
]]></sourcecode>
</section>
</section>
<section anchor="acknowledgements" numbered="false">
<name>Acknowledgements</name>
<t>Thanks to <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"/>, <contact
fullname="Orie Steele"/>, <contact fullname="Tina Tsou"/>, <contact
fullname="Gunter Van de Velde"/>, <contact fullname="Éric Vyncke"/>,
and <contact fullname="Erik Wilde"/> for their reviews, suggestions, and
support.</t>
</section>
</back>
]]></artwork></figure> <!-- [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?
-->
</section> <!-- [rfced] FYI - We have added expansions for the following abbreviations
</section> per Section 3.6 of RFC 7322 ("RFC Style Guide"). Please review each
<section anchor="acknowledgements"><name>Acknowledgements</name> expansion in the document carefully to ensure correctness.
<t>Thanks to Jan Algermissen, Phil Archer, Tim Bray, Ben Bucksch, Sanjay Cross-Origin Resource Sharing (CORS)
Dalal, David Dong, Erik Kline, Mallory Knodel, Murray Kucherawy, Max Fully Qualified Domain Name (FQDN)
Maton, Darrel Miller, Mark Nottingham, Roberto Polli, Joey Salazar, Top-Level Domain (TLD)
Rich Salz, Herbert Van De Sompel, Orie Steele, Tina Tsou, -->
Gunter Van Der Velde, Eric Vyncke, and Erik Wilde for their reviews,
suggestions and support.</t>
</section> <!-- [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.
</back> Please consider whether the "type" attribute for these sourcecode
elements should be set to "json", "pseudocode", or something else.
<!-- ##markdown-source: The current list of preferred values for "type" is available at
H4sIAAAAAAAAA+0923IbN5bvrOI/YOgHS1mSkpybw/FkRrGUWLEuHkmOK5VK <https://www.rfc-editor.org/rpc/wiki/doku.php?id=sourcecode-types>.
xSAJkj1qdnMa3ZIZleZb9lv2y/bcgAaaFzueZHcfdnZmLXU3gIODc79AvV6v If the current list does not contain an applicable type, feel free to
3SqTMjUD1dGLpDfSpU7z6UBpdWfStHeT5XeZen15onQ2VmmS3ajCpLpM8kyV suggest additions for consideration.
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
7mkD1E//OIxfVkOTqR9MMYTxs+jVcZHcAN1lmclsPCYZ3agfdKbGcCwayDh6
ez3L59riqdWUStxqhkBRcDjxlvkxCWYFL2GtZB3FfUnKa91R3ZkhCjyvOwM5
WUxGFv/f/v7+AUnC95zQWiY6x90e32pEQrvV6/WUHlqkDSLF61liFRBGhfoJ
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
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> </rfc>
 End of changes. 143 change blocks. 
989 lines changed or deleted 971 lines changed or added

This html diff was produced by rfcdiff 1.48.