APIカタログ生成ツール
公開APIをまとめて登録すると、RFC 9727が /.well-known/api-catalog に求めるJSON linksetと、適切なメディアタイプで配信するnginx設定を生成できます。
{
"linkset": [
{
"anchor": "https://api.example.com/v1",
"service-desc": [
{
"href": "https://api.example.com/v1/openapi.json",
"type": "application/openapi+json"
}
],
"service-doc": [
{
"href": "https://example.com/docs/api",
"type": "text/html"
}
],
"status": [
{
"href": "https://status.example.com"
}
]
}
]
}
location = /.well-known/api-catalog {
default_type application/linkset+json;
add_header Link '</.well-known/api-catalog>; rel="api-catalog"';
try_files /.well-known/api-catalog =404;
}
ファイルを /.well-known/api-catalog にアップロードし、application/linkset+json として配信してください。nginx設定ではこのメディアタイプを指定し、RFC 9727がHEADリクエストに求めるrel="api-catalog"付きのLinkヘッダーを追加します。
APIカタログを公開する理由
APIを呼び出すエージェントは、まずAPIを見つける必要があります。2025年6月に公開されたRFC 9727は、その検索の起点として、既知のURL /.well-known/api-catalog と、どのページからでもリンクできるapi-catalogリンク関係を定めています。
カタログはJSON形式のlinksetです。各エントリはAPIのベースURLを起点とし、機械可読な仕様(service-desc。通常はOpenAPIファイル)、人間向けのドキュメント(service-doc)、ステータスページにリンクします。クライアントはドキュメントをクロールせずに、小さなファイルを1つ読むだけで済みます。
RFCでは、レスポンスのContent-Typeをapplication/linkset+jsonにし、https://www.rfc-editor.org/info/rfc9727 のprofileを指定することが推奨されています。どのエージェントがこのファイルをリクエストするかは、まだデータがありません。ただし、公開するのは静的ファイル1つだけです。
api-catalogについてよくある質問
/.well-known/api-catalogとは何ですか?
RFC 9727で定められた、組織のAPI一覧を機械可読な形式で公開する場所です。ファイルはJSON linksetで、各APIから仕様、ドキュメント、ステータスへのリンクを提供します。クライアントはこの場所から直接、またはapi-catalogリンク関係をたどって見つけられます。
api-catalogに必要なContent-Typeは何ですか?
RFC 9727では、application/linkset+jsonを指定し、https://www.rfc-editor.org/info/rfc9727 のprofileパラメーターを付けることが推奨されています。このページのnginx設定はメディアタイプとLinkヘッダーを設定します。サーバーの設定で対応できる場合は、profileパラメーターを追加してください。
カタログの公開にOpenAPIファイルは必要ですか?
いいえ。この生成ツールでは、各エントリに必要なのはAPIのベースURLだけです。仕様、ドキュメント、ステータスへのリンクは任意です。OpenAPI仕様があれば、クライアントは文章を読まずにエンドポイントを把握できるため、用意している場合は追加してください。
api-catalogとllms.txtの違いは何ですか?
api-catalogは、APIを呼び出すソフトウェア向けにAPIをJSONリンクとして一覧化するIETF RFCです。llms.txtは、ドキュメントを読む言語モデル向けにページをMarkdownで索引化する提案です。用途が異なるため、両方を公開できます。