dotsagent.io
言語:日本語
RFC 9727

APIカタログ生成ツール

公開APIをまとめて登録すると、RFC 9727が /.well-known/api-catalog に求めるJSON linksetと、適切なメディアタイプで配信するnginx設定を生成できます。

API 1
/.well-known/api-catalog
{
  "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"
        }
      ]
    }
  ]
}
nginx
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で索引化する提案です。用途が異なるため、両方を公開できます。

出典

  1. rfc-editor.org/rfc/rfc9727
  2. rfc-editor.org/rfc/rfc9264
  3. rfc-editor.org/rfc/rfc8631