rfc9727v1.txt		rfc9727.txt
	skipping to change at line 52 ¶		skipping to change at line 52 ¶
	to this document. Code Components extracted from this document must		to this document. Code Components extracted from this document must
	include Revised BSD License text as described in Section 4.e of the		include Revised BSD License text as described in Section 4.e of the
	Trust Legal Provisions and are provided without warranty as described		Trust Legal Provisions and are provided without warranty as described
	in the Revised BSD License.		in the Revised BSD License.
	Table of Contents		Table of Contents
	1. Introduction		1. Introduction
	1.1. Goals and Non-Goals		1.1. Goals and Non-Goals
	1.2. Notational Conventions		1.2. Notational Conventions
	2. Using the 'api-catalog' Well-Known URI		2. Using the "api-catalog" Well-Known URI
	3. The api-catalog Link Relation		3. The api-catalog Link Relation
	3.1. Using Additional Link Relations		3.1. Using Additional Link Relations
	4. The API Catalog Document		4. The API Catalog Document
	4.1. API Catalog Contents		4.1. API Catalog Contents
	4.2. API Catalog Formats		4.2. API Catalog Formats
	4.3. Nesting API Catalog Links		4.3. Nesting API Catalog Links
	5. Operational Considerations		5. Operational Considerations
	5.1. Accounting for APIs Distributed Across Multiple Domains		5.1. Accounting for APIs Distributed Across Multiple Domains
	5.2. Internal Use of api-catalog for Private APIs		5.2. Internal Use of api-catalog for Private APIs
	5.3. Scalability Guidelines		5.3. Scalability Guidelines
	5.4. Monitoring and Maintenance		5.4. Monitoring and Maintenance
	5.5. Integration with Existing API Management Frameworks		5.5. Integration with Existing API Management Frameworks
	6. Conformance to RFC 8615		6. Conformance to RFC 8615
	6.1. Path Suffix		6.1. Path Suffix
	6.2. Formats and Associated Media Types		6.2. Formats and Associated Media Types
	6.3. Registration of the api-catalog Well-Known URI
	7. IANA Considerations		7. IANA Considerations
	7.1. The api-catalog Well-Known URI		7.1. The api-catalog Well-Known URI
	7.2. The api-catalog Link Relation		7.2. The api-catalog Link Relation
	7.3. The api-catalog Profile URI		7.3. The api-catalog Profile URI
	8. Security Considerations		8. Security Considerations
	9. References		9. References
	9.1. Normative References		9.1. Normative References
	9.2. Informative References		9.2. Informative References
	Appendix A. Example API Catalog Documents		Appendix A. Example API Catalog Documents
	A.1. Using Linkset with RFC 8631 Relations		A.1. Using Linkset with Link Relations Defined in RFC 8631
	A.2. Using Linkset with Bookmarks		A.2. Using Linkset with Bookmarks
	A.3. Other API Catalog Formats		A.3. Other API Catalog Formats
	A.4. Nesting API Catalog Links		A.4. Nesting API Catalog Links
	Acknowledgements		Acknowledgements
	Author's Address		Author's Address
	1. Introduction		1. Introduction
	An application may publish APIs to encourage requests for interaction		An application may publish APIs to encourage requests for interaction
	from external parties. Such APIs must be discovered before they may		from external parties. Such APIs must be discovered before they may
	be used, i.e., the external party needs to know what APIs a given		be used, i.e., the external party needs to know what APIs a given
	Publisher exposes, their purpose, any policies for usage, and the		Publisher exposes, their purpose, any policies for usage, and the
	endpoint to interact with each API. To facilitate automated		endpoint to interact with each API. To facilitate automated
	discovery of this information and automated usage of the APIs, this		discovery of this information and automated usage of the APIs, this
	document proposes:		document proposes:
	* a well-known URI [WELL-KNOWN], 'api-catalog', that is encoded as a		* a well-known URI [WELL-KNOWN], "api-catalog", that is encoded as a
	URI reference to an API catalog document describing a Publisher's		URI reference to an API catalog document describing a Publisher's
	API endpoints.		API endpoints.
	* a link relation [WEB-LINKING], 'api-catalog', of which the target		* a link relation [WEB-LINKING], "api-catalog", of which the target
	resource is the Publisher's API catalog document.		resource is the Publisher's API catalog document.
	1.1. Goals and Non-Goals		1.1. Goals and Non-Goals
	The primary goal is to facilitate the automated discovery of a		The primary goal of this document is to facilitate the automated
	Publisher's public API endpoints, along with metadata that describes		discovery of a Publisher's public API endpoints, along with metadata
	the purpose and usage of each API, by specifying a well-known URI		that describes the purpose and usage of each API, by specifying a
	that returns an API catalog document. The API catalog document is		well-known URI that returns an API catalog document. The API catalog
	primarily machine-readable to enable automated discovery and usage of		document is primarily machine-readable to enable automated discovery
	APIs, and it may also include links to human-readable documentation		and usage of APIs, and it may also include links to human-readable
	(see the example in Appendix A.1).		documentation (see the example in Appendix A.1).
	Non-goals: This document does not mandate paths for API endpoints,		Non-goals: This document does not mandate paths for API endpoints,
	i.e., it does not mandate that my_example_api's endpoint should be		i.e., it does not mandate that my_example_api's endpoint should be
	https://www.example.com/.well-known/api-catalog/my_example_api, nor		https://www.example.com/.well-known/api-catalog/my_example_api, nor
	even to be hosted at www.example.com (although it is not forbidden to		even to be hosted at www.example.com (although it is not forbidden to
	do so).		do so).
	1.2. Notational Conventions		1.2. Notational Conventions
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	skipping to change at line 146 ¶		skipping to change at line 145 ¶
	(FQDNs) "www.example.com", "developer.example.com",		(FQDNs) "www.example.com", "developer.example.com",
	"apis.example.com", "apis.example.net", "gaming.example.com", and		"apis.example.com", "apis.example.net", "gaming.example.com", and
	"iot.example.net", where the .com and .net Top-Level Domains (TLDs)		"iot.example.net", where the .com and .net Top-Level Domains (TLDs)
	and various subdomains are simply used to illustrate that the		and various subdomains are simply used to illustrate that the
	"example" Publisher may have their API portfolio distributed across		"example" Publisher may have their API portfolio distributed across
	various domains for which they are the authority. Scenarios where		various domains for which they are the authority. Scenarios where
	the Publisher "example" is not the authority for a given _.example._		the Publisher "example" is not the authority for a given _.example._
	domain are made explicit in the text.		domain are made explicit in the text.
	In this document, "API" refers to the specification resources		In this document, "API" refers to the specification resources
	required for an external party (or in the case of 'private' APIs, an		required for an external party (or in the case of "private" APIs, an
	internal party) to implement software that uses the Publisher's API.		internal party) to implement software that uses the Publisher's API.
	The specification recommends the use of TLS. Hence, "HTTPS" and		The specification recommends the use of TLS. Hence, "HTTPS" and
	"https://" are used throughout.		"https://" are used throughout.
	2. Using the 'api-catalog' Well-Known URI		2. Using the "api-catalog" Well-Known URI
	The api-catalog well-known URI is intended for HTTPS servers that		The api-catalog well-known URI is intended for HTTPS servers that
	publish APIs.		publish APIs.
	* The API catalog MUST be named "api-catalog" in a well-known		* The API catalog MUST be named "api-catalog" in a well-known
	location as described by [WELL-KNOWN].		location as described by [WELL-KNOWN].
	* The location of the API catalog document is decided by the		* The location of the API catalog document is decided by the
	Publisher. The /.well-known/api-catalog URI provides a convenient		Publisher. The /.well-known/api-catalog URI provides a convenient
	reference to that location.		reference to that location.
	skipping to change at line 179 ¶		skipping to change at line 178 ¶
	* SHALL resolve an HTTPS HEAD request to /.well-known/api-catalog		* SHALL resolve an HTTPS HEAD request to /.well-known/api-catalog
	with a response including a Link header with the relation(s)		with a response including a Link header with the relation(s)
	defined in Section 3.		defined in Section 3.
	3. The api-catalog Link Relation		3. The api-catalog Link Relation
	This document introduces a new link relation [WEB-LINKING], "api-		This document introduces a new link relation [WEB-LINKING], "api-
	catalog". This identifies a target resource that represents a list		catalog". This identifies a target resource that represents a list
	of APIs available from the Publisher of the link context. The target		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		resource URI may be /.well-known/api-catalog or any other URI chosen
	by the Publisher. For example, the Publisher 'example' could include		by the Publisher. For example, the Publisher "example" could include
	the api-catalog link relation in the HTTP header and/or content		the api-catalog link relation in the HTTP header and/or content
	payload when responding to a request to https://www.example.com:		payload when responding to a request to https://www.example.com:
	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>
	skipping to change at line 206 ¶		skipping to change at line 205 ¶
	<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>
	3.1. Using Additional Link Relations		3.1. Using Additional Link Relations
	* "item" [RFC6573]. When used in an API catalog document, the		When used in an API catalog document, the "item" [RFC6573] link
	"item" link relation identifies a target resource that represents		relation identifies a target resource that represents an API that is
	an API that is a member of the API catalog.		a member of the API catalog.
	* Other link relations may be utilised in an API catalog to convey		Other link relations may be utilised in an API catalog to convey
	metadata descriptions for API links.		metadata descriptions for API links.
	4. The API Catalog Document		4. The API Catalog Document
	The API catalog is a document listing a Publisher's APIs. The		The API catalog is a document listing a Publisher's APIs. The
	Publisher may host the API catalog document at any URI(s) they		Publisher may host the API catalog document at any URI(s) they
	choose. As illustration, the API catalog document URI of		choose. For example, the API catalog document URI of
	https://www.example.com/my_api_catalog.json can be requested directly		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,		or via a request to https://www.example.com/.well-known/api-catalog,
	which the Publisher will resolve to https://www.example.com/		which the Publisher will resolve to https://www.example.com/
	my_api_catalog.		my_api_catalog.
	4.1. API Catalog Contents		4.1. API Catalog Contents
	The API catalog MUST include hyperlinks to API endpoints, and is		The API catalog MUST include hyperlinks to API endpoints. It is
	RECOMMENDED to include useful metadata, such as usage policies, API		RECOMMENDED that the API catalog also includes useful metadata, such
	version information, links to the OpenAPI Specification [OAS]		as usage policies, API version information, links to the OpenAPI
	definitions for each API, etc. If the Publisher does not include		Specification [OAS] definitions for each API, etc. If the Publisher
	that metadata directly in the API catalog document, they SHOULD make		does not include that metadata directly in the API catalog document,
	that metadata available at the API endpoint URIs they have listed		they SHOULD make that metadata available at the API endpoint URIs
	(see Appendix A.2 for an example).		they have listed (see Appendix A.2 for an example).
	4.2. API Catalog Formats		4.2. API Catalog Formats
	The Publisher MUST publish the API catalog document in the Linkset		The Publisher MUST publish the API catalog document in the Linkset
	format application/linkset+json (Section 4.2 of [RFC9264]). The		format application/linkset+json (Section 4.2 of [RFC9264]). The
	Linkset SHOULD include a profile parameter (Section 5 of [RFC9264])		Linkset SHOULD include a profile parameter (Section 5 of [RFC9264])
	with a Profile URI [RFC7284] value of 'https://www.rfc-		with a Profile URI [RFC7284] value of "https://www.rfc-
	editor.org/info/rfc9727' to indicate the Linkset is representing an		editor.org/info/rfc9727" to indicate the Linkset is representing an
	API catalog document as defined above. Appendix A includes example		API catalog document as defined above. Appendix A includes example
	API catalog documents based on the Linkset format.		API catalog documents based on the Linkset format.
	The Publisher MAY make additional formats available via content		The Publisher MAY make additional formats available via content
	negotiation (Section 12 of [HTTP]) to their /.well-known/api-catalog		negotiation (Section 12 of [HTTP]) to their /.well-known/api-catalog
	location. A non-exhaustive list of such formats that support the		location. A non-exhaustive list of such formats that support the
	automated discovery and machine (and human) usage of a Publisher's		automated discovery and machine (and human) usage of a Publisher's
	APIs is listed at Appendix A.3. If a Publisher already lists their		APIs is listed at Appendix A.3. If a Publisher already lists their
	APIs in a format other than Linkset, but wishes to utilise the		APIs in a format other than Linkset, but wishes to utilise the
	/.well-known/api-catalog URI, then:		/.well-known/api-catalog URI, then:
	* They MUST also implement a Linkset with, at minimum, hyperlinks to		* They MUST also implement a Linkset with, at minimum, hyperlinks to
	API endpoints; see Appendix A.2.		API endpoints; see Appendix A.2.
	* They MAY support content negotiation at the /.well-known/api-		* They MAY support content negotiation at the /.well-known/api-
	catalog URI to allow for the return of their existing format.		catalog URI to allow for the return of their existing format.
	4.3. Nesting API Catalog Links		4.3. Nesting API Catalog Links
	An API catalog may itself contain links to other API catalogs by		An API catalog may itself contain links to other API catalogs by
	using the 'api-catalog' relation type for each link. An example of		using the "api-catalog" relation type for each link. An example of
	this is given in Appendix A.4.		this is given in Appendix A.4.
	5. Operational Considerations		5. Operational Considerations
	5.1. Accounting for APIs Distributed Across Multiple Domains		5.1. Accounting for APIs Distributed Across Multiple Domains
	A Publisher ("example") may have their APIs hosted across multiple		A Publisher ("example") may have their APIs hosted across multiple
	domains that they manage, e.g., at www.example.com,		domains that they manage, e.g., at www.example.com,
	developer.example.com, apis.example.com, apis.example.net, etc. They		developer.example.com, apis.example.com, apis.example.net, etc. They
	may also use a third-party API hosting provider that hosts APIs on a		may also use a third-party API hosting provider that hosts APIs on a
	skipping to change at line 299 ¶		skipping to change at line 298 ¶
	latest API catalog is returned.		latest API catalog is returned.
	For example, if the Publisher's primary API portal is		For example, if the Publisher's primary API portal is
	https://apis.example.com, then https://apis.example.com/.well-known/		https://apis.example.com, then https://apis.example.com/.well-known/
	api-catalog should resolve to the location of the Publisher's latest		api-catalog should resolve to the location of the Publisher's latest
	API catalog document. If the Publisher is also the domain authority		API catalog document. If the Publisher is also the domain authority
	for www.example.net, which also hosts a selection of their APIs, then		for www.example.net, which also hosts a selection of their APIs, then
	a request to https://www.example.net/.well-known/api-catalog should		a request to https://www.example.net/.well-known/api-catalog should
	redirect to https://apis.example.com/.well-known/api-catalog.		redirect to https://apis.example.com/.well-known/api-catalog.
	If the Publisher is not the domain authority for www.example.net --		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’s API Catalog MAY include a link to the API
	then the Publisher MAY include a link in its own API catalog to that		catalog of the third-party that is the domain authority for
	third-party domain's API catalog. For example, the API catalog		www.example.net. For example, the API catalog available at
	available at https://apis.example.com/.well-known/api-catalog may		https://apis.example.com/.well-known/api-catalog may list APIs hosted
	list APIs hosted at apis.example.com and also link to the API catalog		at apis.example.com and also link to the API catalog hosted at
	hosted at https://www.example.net/.well-known/api-catalog using the		https://www.example.net/.well-known/api-catalog using the "api-
	"api-catalog" link relation:		catalog" link relation:
	{		{
	"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"
	},		},
	{		{
	skipping to change at line 351 ¶		skipping to change at line 350 ¶
	* Maintaining the catalog entries to ensure they are up to date and		* Maintaining the catalog entries to ensure they are up to date and
	correcting any errors.		correcting any errors.
	* Restricting the catalog size to help reduce network and client-		* Restricting the catalog size to help reduce network and client-
	processing overheads.		processing overheads.
	In both cases, a Publisher may benefit from grouping their APIs,		In both cases, a Publisher may benefit from grouping their APIs,
	providing an API catalog document for each group and using the main		providing an API catalog document for each group and using the main
	API catalog hosted at /.well-known/api-catalog to provide links to		API catalog hosted at /.well-known/api-catalog to provide links to
	these. For example, a Publisher may decide to group their APIs		these. For example, a Publisher may decide to group their APIs
	according to a business category (e.g., 'gaming APIs', 'anti-fraud		according to a business category (e.g., "gaming APIs", "anti-fraud
	APIs', etc.), a technology category (e.g., 'IOT', 'networks', 'AI',		APIs", etc.), a technology category (e.g., "IOT", "networks", "AI",
	etc.), or any other criterion. This grouping may already be implicit		etc.), or any other criterion. This grouping may be implicit where
	where the Publisher has already published their APIs across multiple		the Publisher has already published their APIs across multiple
	domains, e.g., at gaming.example.com, iot.example.net, etc.		domains, e.g., at gaming.example.com, iot.example.net, etc.
	Section 4.3 shows how the API catalog at /.well-known/api-catalog can		Section 4.3 shows how the API catalog at /.well-known/api-catalog can
	use the api-catalog link relation to point to other API catalogs.		use the api-catalog link relation to point to other API catalogs.
	The Publisher SHOULD consider caching and compression techniques to		The Publisher SHOULD consider caching and compression techniques to
	reduce the network overhead of large API catalogs.		reduce the network overhead of large API catalogs.
	5.4. Monitoring and Maintenance		5.4. Monitoring and Maintenance
	skipping to change at line 473 ¶		skipping to change at line 472 ¶
	The api-catalog URI SHALL be appended to the /.well-known/ path-		The api-catalog URI SHALL be appended to the /.well-known/ path-
	prefix for "well-known locations".		prefix for "well-known locations".
	6.2. Formats and Associated Media Types		6.2. Formats and Associated Media Types
	A /.well-known/api-catalog location MUST support the Linkset		A /.well-known/api-catalog location MUST support the Linkset
	[RFC9264] format of application/linkset+json and MAY also support the		[RFC9264] format of application/linkset+json and MAY also support the
	other formats via content negotiation.		other formats via content negotiation.
	6.3. Registration of the api-catalog Well-Known URI
	See Section 7 considerations below.
	7. IANA Considerations		7. IANA Considerations
	7.1. The api-catalog Well-Known URI		7.1. The api-catalog Well-Known URI
	This specification registers the "api-catalog" well-known URI in the		This specification registers the "api-catalog" well-known URI in the
	"Well-Known URIs" registry as defined by [WELL-KNOWN].		"Well-Known URIs" registry as defined by [WELL-KNOWN].
	URI Suffix: api-catalog		URI Suffix: api-catalog
	Reference: RFC 9727		Reference: RFC 9727
	Status: permanent		Status: permanent
	skipping to change at line 551 ¶		skipping to change at line 546 ¶
	unnecessary metadata about any internal domains (e.g.,		unnecessary metadata about any internal domains (e.g.,
	https://internal.example.com).		https://internal.example.com).
	For the internal/private APIs scenario, the Publisher SHOULD take		For the internal/private APIs scenario, the Publisher SHOULD take
	steps to ensure that appropriate controls, such as Cross-Origin		steps to ensure that appropriate controls, such as Cross-Origin
	Resource Sharing (CORS) policies and access control lists, are in		Resource Sharing (CORS) policies and access control lists, are in
	place to ensure only authorised roles and systems may access an		place to ensure only authorised roles and systems may access an
	internal api-catalog well-known URI.		internal api-catalog well-known URI.
	A comprehensive API catalog that is regularly audited may assist the		A comprehensive API catalog that is regularly audited may assist the
	Publisher in decommissioning 'zombie' APIs, i.e., legacy/obsolete		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.		monitored, patched, or updated.
	Note the registration of domain names and associated policies is out		Note the registration of domain names and associated policies is out
	of scope of this document.		of scope of this document.
	9. References		9. References
	9.1. Normative References		9.1. Normative References
	skipping to change at line 602 ¶		skipping to change at line 597 ¶
	DOI 10.17487/RFC8288, October 2017,		DOI 10.17487/RFC8288, October 2017,
	<https://www.rfc-editor.org/info/rfc8288>.		<https://www.rfc-editor.org/info/rfc8288>.
	[WELL-KNOWN]		[WELL-KNOWN]
	Nottingham, M., "Well-Known Uniform Resource Identifiers		Nottingham, M., "Well-Known Uniform Resource Identifiers
	(URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019,		(URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019,
	<https://www.rfc-editor.org/info/rfc8615>.		<https://www.rfc-editor.org/info/rfc8615>.
	9.2. Informative References		9.2. Informative References
	[APIsjson] Lane, K. and S. Willmott, "API Discovery Format", 9		[APIsjson] Lane, K. and S. Willmott, "API Discovery Format", 6
	January 2020,		November 2024,
	<http://apisjson.org/format/apisjson_0.16.txt>.		<https://apisjson.org/format/apisjson_0.19.txt>. Latest
			version available at <https://apisjson.org/>.
	[HAL] Kelly, M., "JSON Hypertext Application Language", Work in		[HAL] Kelly, M., "JSON Hypertext Application Language", Work in
	Progress, Internet-Draft, draft-kelly-json-hal-11, 19		Progress, Internet-Draft, draft-kelly-json-hal-11, 19
	October 2023, <https://datatracker.ietf.org/doc/html/		October 2023, <https://datatracker.ietf.org/doc/html/
	draft-kelly-json-hal-11>.		draft-kelly-json-hal-11>.
	[OAS] Miller, D., Ed., Whitlock, J., Ed., Gardiner, M., Ed.,		[OAS] Miller, D., Ed., Andrews, H., Ed., Whitlock, J., Ed.,
	Ralphson, M., Ed., Ratovsky, R., Ed., and U. Sarid, Ed.,		Mitchell, L., Ed., Gardiner, M., Ed., Quintero, M., Ed.,
	"OpenAPI Specification v3.1.0", 15 February 2021,		Kistler, M., Ed., Handl, R., Ed., and R. Ratovsky, Ed.,
	<https://spec.openapis.org/oas/latest>.		"OpenAPI Specification v3.1.0", 24 October 2024,
			<https://spec.openapis.org/oas/latest>. Latest version
			available at <https://spec.openapis.org/oas/latest.html>.
	[RESTdesc] Verborgh, R., Mannens, E., Van de Walle, R., and T.		[RESTdesc] Verborgh, R., Mannens, E., Van de Walle, R., and T.
	Steiner, "RESTdesc", 15 September 2023,		Steiner, "RESTdesc", 2025,
	<http://apisjson.org/format/apisjson_0.16.txt>.		<https://restdesc.org/about/descriptions>.
	[RFC8631] Wilde, E., "Link Relation Types for Web Services",		[RFC8631] Wilde, E., "Link Relation Types for Web Services",
	RFC 8631, DOI 10.17487/RFC8631, July 2019,		RFC 8631, DOI 10.17487/RFC8631, July 2019,
	<https://www.rfc-editor.org/info/rfc8631>.		<https://www.rfc-editor.org/info/rfc8631>.
	[WebAPIext]		[WebAPIext]
	Ralphson, M., Ed. and N. Evans, Ed., "WADG0001 WebAPI type		Ralphson, M., Ed. and N. Evans, Ed., "WADG0001 WebAPI type
	extension", Draft Community Group Report, 8 July 2020,		extension", Draft Community Group Report, 8 July 2020,
	<https://webapi-discovery.github.io/rfcs/rfc0001.html>.		<https://webapi-discovery.github.io/rfcs/rfc0001.html>.
	Appendix A. Example API Catalog Documents		Appendix A. Example API Catalog Documents
	This section is informative and provides and example of an API		This section is informative and provides and example of an API
	catalog document using the Linkset format.		catalog document using the Linkset format.
	A.1. Using Linkset with RFC 8631 Relations		A.1. Using Linkset with Link Relations Defined in RFC 8631
	This example uses the Linkset format [RFC9264] and the following link		This example uses the Linkset format [RFC9264] and the following link
	relations defined in [RFC8631]:		relations defined in [RFC8631]:
	"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 [OAS]		primarily intended for machine consumption (for example, the [OAS]
	specification, YAML, or JSON file).		specification, YAML, or JSON file).
	"service-doc": Used to link to API documentation that is primarily		"service-doc": Used to link to API documentation that is primarily
	intended for human consumption (an example of human-readable		intended for human consumption (an example of human-readable
	skipping to change at line 787 ¶		skipping to change at line 785 ¶
	* A RESTDesc semantic description for hypermedia APIs [RESTdesc].		* A RESTDesc semantic description for hypermedia APIs [RESTdesc].
	* A Hypertext Application Language document [HAL].		* A Hypertext Application Language document [HAL].
	* An extension to the Schema.org WebAPI type [WebAPIext].		* An extension to the Schema.org WebAPI type [WebAPIext].
	A.4. Nesting API Catalog Links		A.4. Nesting API Catalog Links
	In this example, a request to the /.well-known/api-catalog URI		In this example, a request to the /.well-known/api-catalog URI
	returns an array of links of relation type 'api-catalog'. This can		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		be useful to Publishers with a large number of APIs who wish to group
	them in smaller catalogs (as described in Section 5.3).		them in smaller catalogs (as described in Section 5.3).
	Client request:		Client request:
	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
	Server response:		Server response:
End of changes. 24 change blocks.
	59 lines changed or deleted		57 lines changed or added
This html diff was produced by rfcdiff 1.48.