Internet Engineering Task Force (IETF) K. Smith
Request for Comments: 9727 Vodafone
Category: Standards Track June 2025
ISSN: 2070-1721
This document defines the "api-catalog" well-known URI and link relation. It is intended to facilitate automated discovery and usage of published Application Programming Interfaces (APIs). A request to the api-catalog resource will return a document providing information about, and links to, the Publisher's APIs.
このドキュメントでは、「API-Catalog」のよく知られているURIとリンクの関係を定義します。公開されたアプリケーションプログラミングインターフェイス（API）の自動発見と使用を促進することを目的としています。API-Catalogリソースへのリクエストは、出版社のAPIに関する情報とリンクを提供するドキュメントを返します。
This is an Internet Standards Track document.
これは、インターネット標準トラックドキュメントです。
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.
このドキュメントは、インターネットエンジニアリングタスクフォース（IETF）の製品です。IETFコミュニティのコンセンサスを表しています。公開レビューを受けており、インターネットエンジニアリングステアリンググループ（IESG）からの出版が承認されています。インターネット標準の詳細については、RFC 7841のセクション2で入手できます。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9727.
このドキュメントの現在のステータス、任意のERRATA、およびそのフィードバックを提供する方法に関する情報は、https://www.rfc-editor.org/info/rfc9727で取得できます。
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.
著作権（c）2025 IETF Trustおよび文書著者として特定された人。無断転載を禁じます。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.
このドキュメントは、BCP 78およびIETFドキュメント（https://trustee.ietf.org/license-info）に関連するIETF Trustの法的規定の対象となります。この文書に関するあなたの権利と制限を説明するので、これらの文書を注意深く確認してください。このドキュメントから抽出されたコードコンポーネントには、セクション4.Eで説明されている法的規定のセクション4.Eで説明されており、改訂されたBSDライセンスで説明されている保証なしで提供されるように、改訂されたBSDライセンステキストを含める必要があります。
1. Introduction
1.1. Goals and Non-Goals
1.2. Notational Conventions
2. Using the "api-catalog" Well-Known URI
3. The api-catalog Link Relation
3.1. Using Additional Link Relations
4. The API Catalog Document
4.1. API Catalog Contents
4.2. API Catalog Formats
4.3. Nesting API Catalog Links
5. Operational Considerations
5.1. Accounting for APIs Distributed Across Multiple Domains
5.2. Internal Use of api-catalog for Private APIs
5.3. Scalability Guidelines
5.4. Monitoring and Maintenance
5.5. Integration with Existing API Management Frameworks
6. Conformance to RFC 8615
6.1. Path Suffix
6.2. Formats and Associated Media Types
7. IANA Considerations
7.1. The api-catalog Well-Known URI
7.2. The api-catalog Link Relation
7.3. The api-catalog Profile URI
8. Security Considerations
9. References
9.1. Normative References
9.2. Informative References
Appendix A. Example API Catalog Documents
A.1. Using Linkset with Link Relations Defined in RFC 8631
A.2. Using Linkset with Bookmarks
A.3. Other API Catalog Formats
A.4. Nesting API Catalog Links
Acknowledgements
Author's Address
An application may publish APIs to encourage requests for interaction 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 Publisher exposes, their purpose, any policies for usage, and the endpoint to interact with each API. To facilitate automated discovery of this information and automated usage of the APIs, this document proposes:
アプリケーションは、APIを公開して、外部の関係者からの対話の要求を奨励する場合があります。このようなAPIは、それらを使用する前に発見する必要があります。つまり、外部の当事者は、特定のパブリッシャーがどのようなAPIが公開しているか、目的、使用に関するポリシー、および各APIと対話するエンドポイントを知る必要があります。この情報の自動発見とAPIの自動化された使用を容易にするために、このドキュメントは次のように提案しています。
* a well-known URI [WELL-KNOWN], "api-catalog", that is encoded as a URI reference to an API catalog document describing a Publisher's API endpoints.
* よく知られているURI [よく知られている]、「API-Catalog」。これは、パブリッシャーのAPIエンドポイントを説明するAPIカタログドキュメントへのURI参照としてエンコードされています。
* a link relation [WEB-LINKING], "api-catalog", of which the target resource is the Publisher's API catalog document.
* リンク関係[Web-Linking]、「API-Catalog」。ターゲットリソースは、パブリッシャーのAPIカタログドキュメントです。
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. The API catalog document is primarily machine-readable to enable automated discovery and usage of APIs, and it may also include links to human-readable documentation (see the example in Appendix A.1).
このドキュメントの主な目標は、APIカタログドキュメントを返すよく知られているURIを指定することにより、各APIの目的と使用法を説明するメタデータとともに、出版社のパブリックAPIエンドポイントの自動発見を促進することです。APIカタログドキュメントは、主にAPIの自動発見と使用を有効にするために機械読み取り可能であり、人間の読み取り可能なドキュメントへのリンクも含めることができます（付録A.1の例を参照）。
Non-goals: This document does not mandate paths for API endpoints, i.e., it does not mandate that my_example_api's endpoint should be 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 do so).
非ゴール：このドキュメントは、APIエンドポイントのパスを義務付けるものではありません。つまり、my_example_apiのエンドポイントがhttps://www.example.com/.well-known/api-catalog/my_example_apiであることを義務付けません。
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. These words may also appear in this document in lower case as plain English words, absent their normative meanings.
「必須」、「必要」、「必須」、「「しなければならない」、「そうはならない」、「そうはならない」、「そうすべき」、「推奨」、「推奨」、「推奨」、「5月」、および「オプション」は、BCP 14 [RFC2119] [RFC8174]に記載されているように解釈されます。これらの単語は、この文書には、規範的な意味がなく、単純な英語の単語として小文字で表示される場合があります。
The terms "content negotiation" and "status code" are from [HTTP]. The term "well-known URI" is from [WELL-KNOWN]. The term "link relation" is from [WEB-LINKING].
「コンテンツネゴシエーション」および「ステータスコード」という用語は[HTTP]からです。「よく知られているウリ」という用語は[よく知られている]からです。「リンク関係」という用語は[Web-Linking]からのものです。
The term "Publisher" refers to an organisation, company, or individual that publishes one or more APIs for use by external third parties. A fictional Publisher named "example" is used throughout this document. The examples use the Fully Qualified Domain Names (FQDNs) "www.example.com", "developer.example.com", "apis.example.com", "apis.example.net", "gaming.example.com", and "iot.example.net", where the .com and .net Top-Level Domains (TLDs) and various subdomains are simply used to illustrate that the "example" Publisher may have their API portfolio distributed across various domains for which they are the authority. Scenarios where the Publisher "example" is not the authority for a given _.example._ domain are made explicit in the text.
「出版社」という用語は、外部の第三者が使用するために1つ以上のAPIを発行する組織、会社、または個人を指します。このドキュメント全体で「例」という名前の架空の出版社が使用されています。例では、完全に認定されたドメイン名（fqdns） "www.example.com"、 "developer.example.com"、 "apis.example.com"、 "apis.example.net"、 "gaming.example.com"、および "iot.example.net"、 "iot.netトップレベルのドメイン（tlds）および" lidest exed exed exed edice of of the "pubribed" and net top-level domains（APIポートフォリオは、それらが権限であるさまざまなドメインに分配されました。パブリッシャーの「例」が特定の_.example._ドメインの権限ではないシナリオは、テキストで明示的になります。
In this document, "API" refers to the specification resources required for an external party (or in the case of "private" APIs, an internal party) to implement software that uses the Publisher's API.
このドキュメントでは、「API」とは、パブリッシャーのAPIを使用するソフトウェアを実装するために、外部の当事者（または「プライベート」APIの場合）に必要な仕様リソースを指します。
The specification recommends the use of TLS. Hence, "HTTPS" and "https://" are used throughout.
仕様では、TLSの使用を推奨しています。したがって、「https」と「https://」が全体に使用されます。
The api-catalog well-known URI is intended for HTTPS servers that publish APIs.
API-Catalog有名なURIは、APIを発行するHTTPSサーバーを対象としています。
* The API catalog MUST be named "api-catalog" in a well-known location as described by [WELL-KNOWN].
* APIカタログは、[よく知られている]で説明されているように、よく知られている場所で「API-Catalog」という名前を付けなければなりません。
* The location of the API catalog document is decided by the Publisher. The /.well-known/api-catalog URI provides a convenient reference to that location.
* APIカタログドキュメントの場所は、パブリッシャーによって決定されます。/.well-known/api-catalog uriは、その場所への便利な参照を提供します。
A Publisher supporting this URI:
このURIをサポートする出版社：
* SHALL resolve an HTTPS GET request to /.well-known/api-catalog and return an API catalog document (as described in Section 4).
* /.well-nking/api-catalogへのHTTPS GETリクエストを解決し、APIカタログドキュメント（セクション4で説明しているように）を返します。
* SHALL resolve an HTTPS HEAD request to /.well-known/api-catalog with a response including a Link header with the relation(s) defined in Section 3.
* セクション3で定義されている関係とリンクヘッダーを含む応答を使用して、 /.well-nking/api-catalogへのHTTPSヘッドリクエストを解決するものとします。
This document introduces a new link relation [WEB-LINKING], "api-catalog". This identifies a target resource that represents a list of APIs available from the Publisher of the link context. The target resource URI may be /.well-known/api-catalog or any other URI chosen by the Publisher. For example, the Publisher "example" could include the api-catalog link relation in the HTTP header and/or content payload when responding to a request to https://www.example.com:
このドキュメントでは、新しいリンク関係[Web-Linking]、「API-Catalog」を紹介します。これは、リンクコンテキストの出版社から利用可能なAPIのリストを表すターゲットリソースを識別します。ターゲットリソースURIは、 /.Well-Nownd/Api-Catalogまたはパブリッシャーが選択したその他のURIである場合があります。たとえば、パブリッシャーの「例」には、https://www.example.comへのリクエストに応答する際に、HTTPヘッダーおよび/またはコンテンツペイロードにAPI-Catalogリンク関係を含めることができます。
HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Location: /index.html
Link: </my_api_catalog.json>; rel=api-catalog
Content-Length: 356
<!DOCTYPE HTML>
<html>
<head>
<title>Welcome to Example Publisher</title>
</head>
<body>
<p>
<a href="my_api_catalog.json" rel="api-catalog">
Example Publisher's APIs
</a>
</p>
<p>(remainder of content)</p>
</body>
</html>
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.
APIカタログドキュメントで使用される場合、「アイテム」[RFC6573]リンク関係は、APIカタログのメンバーであるAPIを表すターゲットリソースを識別します。
Other link relations may be utilised in an API catalog to convey metadata descriptions for API links.
他のリンク関係は、APIカタログで使用されて、APIリンクのメタデータの説明を伝達することができます。
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. For example, the API catalog document URI of https://www.example.com/my_api_catalog.json can be requested directly or via a request to https://www.example.com/.well-known/api-catalog, which the Publisher will resolve to https://www.example.com/ my_api_catalog.
APIカタログは、出版社のAPIをリストするドキュメントです。パブリッシャーは、選択したURIでAPIカタログドキュメントをホストする場合があります。たとえば、https://www.example.com/my_api_catalog.jsonのAPIカタログドキュメントURIは、https://www.example.com/.well-known/api-catalogへのリクエストを介してリクエストすることができます。
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. If the Publisher does not include that metadata directly in the API catalog document, they SHOULD make that metadata available at the API endpoint URIs they have listed (see Appendix A.2 for an example).
APIカタログには、APIエンドポイントへのハイパーリンクを含める必要があります。APIカタログには、使用ポリシー、APIバージョン情報、各APIのOpenAPI仕様[OAS]定義へのリンクなどの便利なメタデータも含めることをお勧めします。パブリッシャーがそのメタデータをAPIカタログに直接含めていない場合は、API Endpoint URISを使用できるメタデータを作成する必要があります。
The Publisher MUST publish the API catalog document in the Linkset format application/linkset+json (Section 4.2 of [RFC9264]). The Linkset SHOULD include a profile parameter (Section 5 of [RFC9264]) with a Profile URI [RFC7284] value of "https://www.rfc-editor.org/info/rfc9727" to indicate the Linkset is representing an API catalog document as defined above. Appendix A includes example API catalog documents based on the Linkset format.
パブリッシャーは、APIカタログドキュメントをリンクセット形式アプリケーション/リンクセット+JSON（[RFC9264]のセクション4.2）で公開する必要があります。リンクセットには、「https://www.rfc-editor.org/info/RFC9727」のプロファイルURI [RFC7284]値のプロファイルパラメーター（[RFC9264]のセクション5）を含める必要があります。付録Aには、リンクセット形式に基づいた例のAPIカタログドキュメントが含まれています。
The Publisher MAY make additional formats available via content negotiation (Section 12 of [HTTP]) to their /.well-known/api-catalog location. A non-exhaustive list of such formats that support the automated discovery and machine (and human) usage of a Publisher's APIs is listed at Appendix A.3. If a Publisher already lists their APIs in a format other than Linkset, but wishes to utilise the /.well-known/api-catalog URI, then:
パブリッシャーは、 /.well-known/api-catalogの場所に、コンテンツネゴシエーション（[http]のセクション12）を介して追加の形式を使用できます。出版社のAPIの自動発見とマシン（および人間）の使用をサポートするこのような形式の非網羅的リストは、付録A.3にリストされています。パブリッシャーが既にリンクセット以外の形式でAPIをリストしているが、 /.well-known/api-catalog uriを利用したい場合は、次のとおりです。
* They MUST also implement a Linkset with, at minimum, hyperlinks to API endpoints; see Appendix A.2.
* また、少なくともAPIエンドポイントにハイパーリンクを使用してリンクセットを実装する必要があります。付録A.2を参照してください。
* They MAY support content negotiation at the /.well-known/api-catalog URI to allow for the return of their existing format.
* 既存のフォーマットの返却を可能にするために、 /.Well-Known/Api-Catalog URIでのコンテンツ交渉をサポートする場合があります。
An API catalog may itself contain links to other API catalogs by using the "api-catalog" relation type for each link. An example of this is given in Appendix A.4.
APIカタログ自体には、各リンクに「API-Catalog」関係タイプを使用して、他のAPIカタログへのリンクを含めることができます。この例は、付録A.4に記載されています。
A Publisher ("example") may have their APIs hosted across multiple domains that they manage, e.g., at www.example.com, developer.example.com, apis.example.com, apis.example.net, etc. They may also use a third-party API hosting provider that hosts APIs on a distinct domain.
パブリッシャー（「例」）は、www.example.com、developer.example.com、apis.example.com、apis.example.netなど、管理する複数のドメインにわたってAPIをホストしている場合があります。
To account for this scenario, it is RECOMMENDED that:
このシナリオを説明するには、次のことをお勧めします。
* The Publisher also publish the api-catalog well-known URI at each of their API domains, e.g., https://apis.example.com/.well-known/ api-catalog, https://developer.example.net/.well-known/api-catalog, etc.
* パブリッシャーは、各APIドメインでAPI-Catalogの有名なURIを公開します。
* An HTTPS GET request to any of these URIs returns the same result, namely, the API catalog document.
* HTTPSは、これらのURISのいずれかにリクエストを取得し、同じ結果、つまりAPIカタログドキュメントを返します。
* The Publisher choose one of their instances of /.well-known/api-catalog as a canonical reference to the location of the latest API catalog since the physical location of the API catalog document is decided by the Publisher and may change. The Publisher's other instances of /.well-known/api-catalog should redirect to this canonical instance of /.well-known/api-catalog to ensure the latest API catalog is returned.
* 出版社は、APIカタログドキュメントの物理的位置はパブリッシャーによって決定され、変更される可能性があるため、最新のAPIカタログの場所への標準的な参照として、 /.Well-Known/Api-Catalogのインスタンスのいずれかを選択します。/.well-known/api-catalogのパブリッシャーの他のインスタンスは、 /.well-known/api-catalogのこの正規のインスタンスにリダイレクトして、最新のAPIカタログが返されるようにする必要があります。
For example, if the Publisher's primary API portal is https://apis.example.com, then https://apis.example.com/.well-known/ api-catalog should resolve to the location of the Publisher's latest API catalog document. If the Publisher is also the domain authority 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 redirect to https://apis.example.com/.well-known/api-catalog.
たとえば、出版社の主要なAPIポータルがhttps://apis.example.comの場合、https://apis.example-com/.well-known/ API-Catalogは、パブリッシャーの最新のAPIカタログドキュメントの場所に解決する必要があります。出版社がwww.example.netのドメイン権限でもある場合、APIの選択もホストしている場合、https://www.example.net/.well-kond/api-catalogへのリクエストはhttps://apis.example.com/.well-nubled/api-catalogにリダイレクトする必要があります。
If the Publisher is not the domain authority for www.example.net, then the Publisher's API Catalog MAY include a link to the API catalog of the third-party that is the domain authority for www.example.net. For example, the API catalog available at https://apis.example.com/.well-known/api-catalog may list APIs hosted at apis.example.com and also link to the API catalog hosted at https://www.example.net/.well-known/api-catalog using the "api-catalog" link relation:
出版社がwww.example.netのドメイン権限でない場合、出版社のAPIカタログには、www.example.netのドメイン権限であるサードパーティのAPIカタログへのリンクが含まれている場合があります。たとえば、https://apis.example.com/.well-known/api-catalogで利用可能なAPIカタログは、apis.example.comでホストされているAPIをリストし、https://www.example.net/.well-known/api-catalogでホストされているAPIカタログにリンクすることもできます。
{
"linkset": [
{
"anchor": "https://www.example.com/.well-known/api-catalog",
"item": [
{
"href": "https://developer.example.com/apis/foo_api"
},
{
"href": "https://developer.example.com/apis/bar_api"
},
{
"href": "https://developer.example.com/apis/cantona_api"
}
],
"api-catalog": "https://www.example.net/.well-known/api-catalog"
}
]
}
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 use. This scenario may incur additional security considerations as noted in Section 8.
出版社は、内部ネットワーク上のAPI-Catalogの有名なURIを、サードパーティの使用を目的としていない内部/プライベートAPIに向けて、認定ユーザー（たとえば、会社の従業員など）をSignpostに使用することを希望する場合があります。このシナリオは、セクション8で述べたように、追加のセキュリティ上の考慮事項が発生する場合があります。
In cases where a Publisher has a large number of APIs potentially deployed across multiple domains, two challenges may arise:
出版社が複数のドメインに潜在的に展開される可能性のある多数のAPIを持っている場合、2つの課題が発生する可能性があります。
* Maintaining the catalog entries to ensure they are up to date and correcting any errors.
* カタログエントリを維持して、それらが最新の状態であることを確認し、エラーを修正します。
* Restricting the catalog size to help reduce network and client-processing overheads.
* ネットワークやクライアント処理のオーバーヘッドを削減するのに役立つカタログサイズを制限します。
In both cases, a Publisher may benefit from grouping their APIs, providing an API catalog document for each group and using the 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. This grouping may be implicit where the Publisher has already published their APIs across multiple domains, e.g., at gaming.example.com, iot.example.net, etc.
どちらの場合も、出版社はAPIをグループ化し、各グループにAPIカタログドキュメントを提供し、 /.Well-Nowned/API-CatalogでホストされているメインAPIカタログを使用してこれらへのリンクを提供することで恩恵を受ける場合があります。たとえば、出版社は、ビジネスカテゴリ（「ゲームのAPI」、「アンチフラードAPI」など）、テクノロジーカテゴリ（「IoT」、「ネットワーク」、「AI」など）、またはその他の基準に従ってAPIをグループ化することを決定する場合があります。このグループ化は、パブリッシャーが既に複数のドメイン、たとえばgaming.example.com、IoT.example.netなどでAPIを公開している場合に暗黙的になる可能性があります。
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.
セクション4.3は、 /.Well-Nownd/API-CatalogのAPIカタログがAPI-Catalogリンク関係を使用して他のAPIカタログをポイントする方法を示しています。
The Publisher SHOULD consider caching and compression techniques to reduce the network overhead of large API catalogs.
パブリッシャーは、大規模なAPIカタログのネットワークオーバーヘッドを削減するために、キャッシュおよび圧縮技術を検討する必要があります。
Publishers are RECOMMENDED to follow operational best practice when hosting API catalog(s), including, but not limited to:
出版社は、APIカタログをホストする際には、以下を含むがこれらに限定されない運用ベストプラクティスに従うことをお勧めします。
* Availability. The Publisher should monitor availability of the API catalog and consider alternate means to resolve requests to /.well-known/api-catalog during planned downtime of hosts.
* 可用性。パブリッシャーは、APIカタログの可用性を監視し、ホストの計画されたダウンタイム中に /.Well-Known/API-Catalogへのリクエストを解決する代替手段を検討する必要があります。
* Performance. Although the performance of APIs listed in an API catalog can demand high transactions per second and low-latency response, the retrieval of the API catalog itself to discover those APIs is less likely to incur strict performance demands. That said, the Publisher should monitor the response time to fulfil a request for the API catalog and determine any necessary improvements (as with any other Web resource the Publisher serves). For large API catalogs, the Publisher should consider the techniques described in Section 5.3.
* パフォーマンス。APIカタログにリストされているAPIのパフォーマンスは、1秒あたりの高いトランザクションと低遅延応答を必要とする可能性がありますが、APIカタログ自体の検索は、それらのAPIを発見することで、厳格なパフォーマンス需要が発生する可能性が低くなります。とはいえ、出版社は応答時間を監視して、APIカタログのリクエストを満たし、必要な改善を決定する必要があります（パブリッシャーが提供する他のWebリソースと同様に）。大規模なAPIカタログの場合、出版社はセクション5.3で説明されている手法を考慮する必要があります。
* Usage. Since the goal of the api-catalog well-known URI is to facilitate discovery of APIs, the Publisher may wish to correlate requests to the /.well-known/api-catalog URI with subsequent requests to the API URIs listed in the catalog.
* 使用法。よく知られているURIのAPI-Catalogの目標はAPIの発見を促進することであるため、出版社はリクエストを/.well-known/api-catalog uriとカタログにリストされたAPI URIへのその後のリクエストと関連付けることを望む場合があります。
* Current data. The Publisher should include the removal of stale API entries from the API catalog as part of their API release lifecycle. The Publisher MAY decide to include metadata regarding legacy API versions or deprecated APIs to help users of those APIs discover up-to-date alternatives.
* 現在のデータ。出版社は、APIリリースライフサイクルの一部として、APIカタログから古いAPIエントリを削除することを含める必要があります。出版社は、レガシーAPIバージョンまたは非推奨APIに関するメタデータを含めることを決定し、これらのAPIのユーザーが最新の代替品を発見できるようにすることができます。
* Correct metadata. The Publisher should include human and/or automated checks for syntax errors in the API catalog. Automated checks include format validation (e.g., to ensure valid JSON syntax) and linting to enforce business rules, such as removing duplicate entries and ensuring descriptions are correctly named with valid values. A proofread of the API catalog as part of the API release lifecycle is RECOMMENDED to detect any errors in business grammar (for example, an API entry that is described with valid syntax, but has been allocated an incorrect or outdated description.)
* 正しいメタデータ。出版社には、APIカタログの構文エラーの人間および/または自動化されたチェックを含める必要があります。自動化されたチェックには、フォーマット検証（有効なJSON構文を確保するための）と、重複エントリの削除や説明の確保などのビジネスルールを実施する糸くずが有効な値で正しく指定されていることが含まれます。APIリリースライフサイクルの一部としてのAPIカタログの校正は、ビジネス文法のエラーを検出するために推奨されます（たとえば、有効な構文で説明されているが、誤った説明または時代遅れの説明が割り当てられているAPIエントリ）。
* Security best practice. See Section 8.
* セキュリティベストプラクティス。セクション8を参照してください。
A Publisher may already utilise an API management framework to produce their API portfolio. These frameworks typically include the publication of API endpoint URIs, deprecation and redirection of legacy API versions, API usage policies and documentation, etc. The api-catalog well-known URI and API catalog document are intended to complement API management frameworks by facilitating the discovery of the framework's outputs -- API endpoints, usage policies, and documentation -- and are not intended to replace any existing API discovery mechanisms the framework has implemented.
パブリッシャーは、API管理フレームワークを既に利用してAPIポートフォリオを作成する場合があります。これらのフレームワークには、通常、APIエンドポイントURIの公開、レガシーAPIバージョンの廃止とリダイレクト、API使用ポリシーとドキュメントなどが含まれます。メカニズムフレームワークが実装しています。
Providers of such frameworks may include the production of an API catalog and the publication of the /.well-known/api-catalog URI as a final pre-release (or post-release) step in the release management workflow. The following steps are recommended.
このようなフレームワークのプロバイダーには、APIカタログの制作と、リリース管理ワークフローの最終的なプレリリース（またはリリース後）ステップとしての /.Well-known/API-Catalog URIの公開が含まれる場合があります。次の手順をお勧めします。
If the /.well-known/api-catalog URI has not been published previously, the framework provider should:
/.well-known/api-catalog uriが以前に公開されていない場合、フレームワークプロバイダーは次のとおりです。
* Collate and check the metadata for each API that will be included in the API catalog. This metadata is likely to already exist in the framework.
* APIカタログに含まれる各APIのメタデータを照合して確認します。このメタデータは、フレームワークに既に存在する可能性があります。
* Determine which metadata to include in the API catalog following the requirements set out in Section 4.1 and the considerations set out in Section 5.
* セクション4.1に記載されている要件とセクション5に記載されている考慮事項に従って、APIカタログに含めるメタデータを決定します。
* Map the chosen metadata to the format(s) described in Section 4.2. The structure suggested in Appendix A.2 may be followed where only the hyperlinks to APIs are to be included in the API catalog. Where possible, the API catalog should include further metadata per the guidance in Section 4.1; in which case, the structure suggested in Appendix A can be utilised and adapted (ensuring compliance to [RFC9264]) to reflect the nature of the chosen metadata.
* 選択したメタデータをセクション4.2で説明した形式にマップします。付録A.2で提案されている構造は、APIカタログにハイパーリンクのみがAPIカタログに含まれる場合があります。可能であれば、APIカタログには、セクション4.1のガイダンスごとにさらにメタデータを含める必要があります。その場合、付録Aで提案されている構造を利用して適応させることができます（[RFC9264]のコンプライアンスを確保する）選択したメタデータの性質を反映します。
* Publish the /.well-known/api-catalog URI following the guidance set out in Section 2.
* セクション2に記載されているガイダンスに従って、 /.well-known/api-catalog uriを公開します。
If the /.well-known/api-catalog URI has previously been published, the framework provider should:
/.well-nking/api-catalog uriが以前に公開されていた場合、フレームワークプロバイダーは次のようにする必要があります。
* Include a step in the release management lifecycle to refresh the API catalog following any changes in API hyperlinks or published metadata. This could include placing triggers on certain metadata fields, so that as they are updated in pre-production on the API framework, the updates are pushed to a pre-production copy of the API catalog to be pushed live when the release is published by the framework.
* リリース管理ライフサイクルにステップを含めて、APIハイパーリンクまたは公開されたメタデータの変更に続いてAPIカタログを更新します。これには、特定のメタデータフィールドにトリガーを配置することが含まれます。これにより、APIフレームワークの事前制作で更新されると、リリースがフレームワークによって公開されたときにライブプッシュするAPIカタログの事前制作コピーに更新がプッシュされます。
The requirements in Section 3 of [WELL-KNOWN] for defining Well-Known URIs are met as described in the following subsections.
有名なURIを定義するための[よく知られている]セクション3の要件は、以下のサブセクションで説明されているように満たされています。
The api-catalog URI SHALL be appended to the /.well-known/ path-prefix for "well-known locations".
API-Catalog URIは、「よく知られている場所」のために / .Well-Nownd/ Path-Prefixに追加されるものとします。
A /.well-known/api-catalog location MUST support the Linkset [RFC9264] format of application/linkset+json and MAY also support the other formats via content negotiation.
a /.well-known/api-catalogの場所は、アプリケーション/リンクセット+jsonのリンクセット[RFC9264]形式をサポートする必要があり、コンテンツネゴシエーションを介して他の形式もサポートする場合があります。
This specification registers the "api-catalog" well-known URI in the "Well-Known URIs" registry as defined by [WELL-KNOWN].
この仕様は、[よく知られている]で定義されている「よく知られているURIS」レジストリで「API-Catalog」のよく知られたURIを登録します。
URI Suffix:
URIサフィックス：
api-catalog
api-catalog
Reference:
参照：
RFC 9727
RFC 9727
Status:
状態：
permanent
永続
Change Controller:
Change Controller：
IETF
IETF
This specification registers the "api-catalog" link relation in the "Link Relation Types" registry by following the procedures per Section 2.1.1.1 of [WEB-LINKING].
この仕様は、[Web-linking]のセクション2.1.1.1ごとに手順に従うことにより、「リンク関係タイプ」レジストリの「API-Catalog」リンクの関係を登録します。
Relation Name:
関係名：
api-catalog
api-catalog
Description:
説明：
Refers to a list of APIs available from the Publisher of the link context.
リンクコンテキストの出版社から利用可能なAPIのリストを指します。
Reference:
参照：
RFC 9727
RFC 9727
This specification registers "https://www.rfc-editor.org/info/ rfc9727" in the "Profile URIs" registry according to [RFC7284].
この仕様は、[RFC7284]に従って「uris」レジストリに「https://www.rfc-editor.org/info/ rfc9727」を登録します。
Profile URI:
プロファイルURI：
https://www.rfc-editor.org/info/rfc9727
https://www.rfc-editor.org/info/rfc9727
Common Name:
一般名：
API catalog
APIカタログ
Description:
説明：
A Profile URI to request or signal a Linkset representing an API catalog.
APIカタログを表すリンクセットを要求または信号するプロファイルURI。
Reference:
参照：
RFC 9727
RFC 9727
For all scenarios:
すべてのシナリオについて：
* TLS SHOULD be used, i.e., make /.well-known/api-catalog available exclusively over HTTPS, to ensure no tampering of the API catalog.
* TLSを使用する必要があります。つまり、APIカタログを改ざんしないように、httpsでのみ /.well-known/api-catalogを使用できます。
* The Publisher SHOULD take into account the security considerations from Section 4 of [WELL-KNOWN].
* 出版社は、[よく知られている]のセクション4からのセキュリティ上の考慮事項を考慮する必要があります。
* The Publisher SHOULD 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.
* 出版社は、展開前にAPIカタログのセキュリティとプライバシーのレビューを実行して、個人、ビジネス、またはその他の機密メタデータを漏らしないようにしたり、リストされているAPIに関連する脆弱性を公開したりする必要があります。
* The Publisher SHOULD enforce read-only privileges for external requests to .well-known/api-catalog and for internal systems and roles that monitor the .well-known/api-catalog URI. Write privileges SHOULD only be granted to roles that perform updates to the API catalog and/or the forwarding rewrite rules for the .well-known/api-catalog URI.
* パブリッシャーは、外部リクエストの.well-known/api-catalogへの読み取り専用特権と、.well-bunding/api-catalog URIを監視する内部システムと役割を強制する必要があります。書き込み特権は、APIカタログの更新を実行し、/または.well-bunding/api-catalog uriの転送を書き換えた役割にのみ付与する必要があります。
* As with any Web offering, it is RECOMMENDED to apply rate-limiting measures to help mitigate abuse and prevent denial-of-service attacks on the API catalog endpoint.
* 他のWeb提供と同様に、乱用の軽減を支援し、APIカタログのエンドポイントでのサービス拒否攻撃を防ぐために、料金制限措置を適用することをお勧めします。
For the public-facing APIs scenario, security teams SHOULD additionally audit the API catalog to ensure no APIs intended solely for internal use have been mistakenly included. For example, a catalog hosted on https://developer.example.com should not expose unnecessary metadata about any internal domains (e.g., https://internal.example.com).
パブリックに向かうAPISシナリオの場合、セキュリティチームはさらに、APIカタログを監査して、内部使用のみを目的としたAPIが誤って含まれていないことを確認する必要があります。たとえば、https://developer.example.comでホストされているカタログは、内部ドメイン（https://internal.example.comなど）について不必要なメタデータを公開しないでください。
For the internal/private APIs scenario, the Publisher SHOULD take steps to ensure that appropriate controls, such as Cross-Origin Resource Sharing (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.
内部/プライベートAPIのシナリオの場合、出版社は、クロスオリジンリソース共有（CORS）ポリシーやアクセス制御リストなどの適切なコントロールが、認定された役割とシステムのみが内部APIカタログの有名なURIにアクセスできるようにするために導入されるように措置を講じる必要があります。
A comprehensive API catalog that is regularly audited may assist the Publisher in decommissioning "zombie" APIs, i.e., legacy/obsolete APIs that should no longer be available. Such APIs represent a security vulnerability as they are unlikely to be supported, monitored, patched, or updated.
定期的に監査されている包括的なAPIカタログは、出版社が「ゾンビ」APIの廃止を支援する場合があります。このようなAPIは、サポート、監視、パッチを適用、更新する可能性は低いため、セキュリティの脆弱性を表しています。
Note the registration of domain names and associated policies is out of scope of this document.
ドメイン名と関連するポリシーの登録は、このドキュメントの範囲外ではありません。
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/info/rfc9110>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC6573] Amundsen, M., "The Item and Collection Link Relations",
RFC 6573, DOI 10.17487/RFC6573, April 2012,
<https://www.rfc-editor.org/info/rfc6573>.
[RFC7284] Lanthaler, M., "The Profile URI Registry", RFC 7284,
DOI 10.17487/RFC7284, June 2014,
<https://www.rfc-editor.org/info/rfc7284>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC9264] Wilde, E. and H. Van de Sompel, "Linkset: Media Types and
a Link Relation Type for Link Sets", RFC 9264,
DOI 10.17487/RFC9264, July 2022,
<https://www.rfc-editor.org/info/rfc9264>.
[WEB-LINKING]
Nottingham, M., "Web Linking", RFC 8288,
DOI 10.17487/RFC8288, October 2017,
<https://www.rfc-editor.org/info/rfc8288>.
[WELL-KNOWN]
Nottingham, M., "Well-Known Uniform Resource Identifiers
(URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019,
<https://www.rfc-editor.org/info/rfc8615>.
[APIsjson] Lane, K. and S. Willmott, "API Discovery Format", 6
November 2024,
<https://apisjson.org/format/apisjson_0.19.txt>. Latest
version available at <https://apisjson.org/>.
[HAL] Kelly, M., "JSON Hypertext Application Language", Work in
Progress, Internet-Draft, draft-kelly-json-hal-11, 19
October 2023, <https://datatracker.ietf.org/doc/html/
draft-kelly-json-hal-11>.
[OAS] Miller, D., Ed., Andrews, H., Ed., Whitlock, J., Ed.,
Mitchell, L., Ed., Gardiner, M., Ed., Quintero, M., Ed.,
Kistler, M., Ed., Handl, R., Ed., and R. Ratovsky, Ed.,
"OpenAPI Specification v3.1.0", 24 October 2024,
<https://spec.openapis.org/oas/latest>. Latest version
available at <https://spec.openapis.org/oas/latest.html>.
[RESTdesc] Verborgh, R., Mannens, E., Van de Walle, R., and T.
Steiner, "RESTdesc", 2025,
<https://restdesc.org/about/descriptions>.
[RFC8631] Wilde, E., "Link Relation Types for Web Services",
RFC 8631, DOI 10.17487/RFC8631, July 2019,
<https://www.rfc-editor.org/info/rfc8631>.
[WebAPIext]
Ralphson, M., Ed. and N. Evans, Ed., "WADG0001 WebAPI type
extension", Draft Community Group Report, 8 July 2020,
<https://webapi-discovery.github.io/rfcs/rfc0001.html>.
This section is informative and provides and example of an API catalog document using the Linkset format.
このセクションは有益であり、リンクセット形式を使用してAPIカタログドキュメントを提供し、例を挙げます。
This example uses the Linkset format [RFC9264] and the following link relations defined in [RFC8631]:
この例では、[RFC8631]で定義されているLinksetフォーマット[RFC9264]と次のリンク関係を使用しています。
"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).
主に機械の消費を目的としたAPIの説明にリンクするために使用されます（たとえば、[OAS]仕様、YAML、またはJSONファイルなど）。
"service-doc":
「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>).
主に人間の消費を目的としたAPIドキュメントにリンクするために使用されます（人間の読み取り可能なドキュメントの例は、IETFインターネットドラフトの提出API命令<https://datatracker.ietf.org/api/submission>）です。
"service-meta":
「サービスメタ」：
Used to link to additional metadata about the API and is primarily intended for machine consumption.
APIに関する追加のメタデータにリンクするために使用され、主に機械消費を目的としています。
"status":
"状態"：
Used to link to the API status (e.g., API "health" indication) for machine and/or human consumption.
マシンおよび/または人間の消費のために、APIステータス（API「健康」指示など）にリンクするために使用されます。
Client request:
クライアントのリクエスト：
GET .well-known/api-catalog HTTP/1.1
Host: example.com
Accept: application/linkset+json
Server response:
サーバーの応答：
HTTP/1.1 200 OK
Date: Mon, 01 Jun 2023 00:00:01 GMT
Server: Apache-Coyote/1.1
Content-Type: application/linkset+json;
profile="https://www.rfc-editor.org/info/rfc9727"
{
"linkset": [
{
"anchor": "https://developer.example.com/apis/foo_api",
"service-desc": [
{
"href": "https://developer.example.com/apis/foo_api/spec",
"type": "application/yaml"
}
],
"status": [
{
"href": "https://developer.example.com/apis/foo_api/status",
"type": "application/json"
}
],
"service-doc": [
{
"href": "https://developer.example.com/apis/foo_api/doc",
"type": "text/html"
}
],
"service-meta": [
{
"href": "https://developer.example.com/apis/foo_api/policies",
"type": "text/xml"
}
]
},
{
"anchor": "https://developer.example.com/apis/bar_api",
"service-desc": [
{
"href": "https://developer.example.com/apis/bar_api/spec",
"type": "application/yaml"
}
],
"status": [
{
"href": "https://developer.example.com/apis/bar_api/status",
"type": "application/json"
}
],
"service-doc": [
{
"href": "https://developer.example.com/apis/bar_api/doc",
"type": "text/plain"
}
]
},
{
"anchor": "https://apis.example.net/apis/cantona_api",
"service-desc": [
{
"href": "https://apis.example.net/apis/cantona_api/spec",
"type": "text/n3"
}
],
"service-doc": [
{
"href": "https://apis.example.net/apis/cantona_api/doc",
"type": "text/html"
}
]
}
]
}
This example also uses the Linkset format [RFC9264] and lists the API endpoints in an array of bookmarks. Each link shares the same context anchor (the well-known URI of the API catalog) and "item" [RFC9264] link relation (to indicate they are an item in the catalog). The intent is that by following a bookmark link, a machine client can discover the purpose and usage policy for each API; hence, the document targeted by the bookmark link should support this.
この例では、リンクセット形式[RFC9264]も使用し、APIエンドポイントを一連のブックマークにリストします。各リンクは、同じコンテキストアンカー（APIカタログのよく知られたURI）と「アイテム」[RFC9264]リンクの関係（カタログのアイテムであることを示すため）を共有します。意図は、ブックマークリンクに従うことにより、マシンクライアントが各APIの目的と使用ポリシーを発見できることです。したがって、ブックマークリンクのターゲットを絞ったドキュメントはこれをサポートする必要があります。
Client request:
クライアントのリクエスト：
GET .well-known/api-catalog HTTP/1.1
Host: example.com
Accept: application/linkset+json
Server response:
サーバーの応答：
HTTP/1.1 200 OK
Date: Mon, 01 Jun 2023 00:00:01 GMT
Server: Apache-Coyote/1.1
Content-Type: application/linkset+json;
profile="https://www.rfc-editor.org/info/rfc9727"
{ "linkset":
[
{ "anchor": "https://www.example.com/.well-known/api-catalog",
"item": [
{"href": "https://developer.example.com/apis/foo_api"},
{"href": "https://developer.example.com/apis/bar_api"},
{"href": "https://developer.example.com/apis/cantona_api"}
]
}
]
}
A non-exhaustive list of other API catalog document formats includes:
他のAPIカタログドキュメント形式の網羅的ではないリストには以下が含まれます。
* An APIs.json document [APIsjson].
* apis.jsonドキュメント[apisjson]。
* A RESTDesc semantic description for hypermedia APIs [RESTdesc].
* HyperMedia API [RestDesc]のRestDESCセマンティック説明。
* A Hypertext Application Language document [HAL].
* ハイパーテキストアプリケーション言語ドキュメント[HAL]。
* An extension to the Schema.org WebAPI type [WebAPIext].
* schema.org webapiタイプ[webapiext]の拡張。
In this example, a request to the /.well-known/api-catalog URI returns an array of links of relation type "api-catalog". This can be useful to Publishers with a large number of APIs who wish to group them in smaller catalogs (as described in Section 5.3).
この例では、 /.well-known/api-catalog URIへのリクエストは、関係タイプ「API-Catalog」のリンクの配列を返します。これは、小規模なカタログにグループ化したい多数のAPIを持つ出版社にとって役立ちます（セクション5.3で説明しています）。
Client request:
クライアントのリクエスト：
GET .well-known/api-catalog HTTP/1.1
Host: example.com
Accept: application/linkset+json
Server response:
サーバーの応答：
HTTP/1.1 200 OK
Date: Mon, 01 Jun 2023 00:00:01 GMT
Server: Apache-Coyote/1.1
Content-Type: application/linkset+json;
profile="https://www.rfc-editor.org/info/rfc9727"
{
"linkset": [
{
"anchor": "https://www.example.com/.well-known/api-catalog",
"api-catalog": [
{
"href": "https://apis.example.com/iot/api-catalog"
},
{
"href": "https://ecommerce.example.com/api-catalog"
},
{
"href": "https://developer.example.com/gaming/api-catalog"
}
]
}
]
}
Thanks to Jan Algermissen, Phil Archer, Tim Bray, Ben Bucksch, Sanjay Dalal, David Dong, Erik Kline, Mallory Knodel, Murray Kucherawy, Max Maton, Darrel Miller, Mark Nottingham, Roberto Polli, Joey Salazar, Rich Salz, Herbert Van De Sompel, Orie Steele, Tina Tsou, Gunter Van de Velde, Éric Vyncke, and Erik Wilde for their reviews, suggestions, and support.
Jan Algermissen、Phil Archer、Tim Bray、Ben Bucksch、Sanjay Dalal、David Dong、Erik Kline、Mallory Knodel、Murray Kucherawy、Max Maton、Darrel Miller、Mark Nottingham、Roberto Polri、Joey Salazar、Rich Salz、HerberVyncke、およびErik Wildeは、レビュー、提案、サポートについて。
Kevin Smith
Vodafone
Email: kevin.smith@vodafone.com
URI: https://www.vodafone.com