เครื่องมือสร้าง API catalog

ระบุ API สาธารณะของคุณเพียงครั้งเดียว แล้วสร้าง JSON linkset ตามที่ RFC 9727 กำหนดให้ใช้ที่ /.well-known/api-catalog พร้อมบล็อก nginx สำหรับให้บริการด้วย media type ที่ถูกต้อง

{
  "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;
}

เหตุผลที่ควรเผยแพร่ API catalog

ก่อนเรียกใช้ API ของคุณ agent ต้องค้นหา API นั้นให้พบก่อน RFC 9727 ซึ่งเผยแพร่ในเดือนมิถุนายน 2025 กำหนดจุดเริ่มต้นที่แน่นอนสำหรับการค้นหานี้ นั่นคือ URL ที่รู้จักกันดี /.well-known/api-catalog พร้อมกับความสัมพันธ์ลิงก์ api-catalog ที่หน้าเว็บใดก็ใช้ชี้ไปยัง catalog ได้

catalog นี้เป็น linkset ในรูปแบบ JSON โดยแต่ละรายการจะอ้างอิง URL หลักของ API และลิงก์ไปยังคำอธิบายที่เครื่องอ่านได้ (service-desc ซึ่งมักเป็นไฟล์ OpenAPI), เอกสารสำหรับผู้ใช้ (service-doc) และหน้าสถานะ ไคลเอ็นต์จึงอ่านไฟล์ขนาดเล็กเพียงไฟล์เดียว แทนการไล่ค้นเอกสารของคุณ

RFC ระบุว่าคำตอบต้องใช้ application/linkset+json และควรมี profile https://www.rfc-editor.org/info/rfc9727 เรายังไม่มีข้อมูลว่า agent ใดบ้างที่ร้องขอไฟล์นี้ แต่คุณสามารถเผยแพร่เป็นไฟล์ static เพียงไฟล์เดียวได้