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 설정 블록은 해당 유형을 지정하고 rel="api-catalog"이 포함된 Link 헤더를 추가합니다. RFC 9727은 HEAD 요청에 이 헤더를 포함하도록 요구합니다.
API 카탈로그를 공개해야 하는 이유
API를 호출하려는 에이전트는 먼저 API를 찾아야 합니다. 2025년 6월에 발표된 RFC 9727은 검색의 고정된 시작점을 제공합니다. 표준 URL인 /.well-known/api-catalog와 모든 페이지에서 해당 URL을 가리킬 수 있는 api-catalog 링크 관계입니다.
카탈로그는 JSON linkset입니다. 각 항목은 API 기본 URL을 기준으로 하며, 기계가 읽을 수 있는 설명(service-desc, 일반적으로 OpenAPI 파일), 사용자용 문서(service-doc), 상태 페이지를 연결합니다. 클라이언트는 문서를 크롤링하는 대신 작은 파일 하나만 읽으면 됩니다.
RFC는 응답에 application/linkset+json을 사용하고 https://www.rfc-editor.org/info/rfc9727 프로필을 포함하도록 권고합니다. 어떤 에이전트가 이 파일을 요청하는지에 관한 데이터는 아직 없지만, 정적 파일 하나만 공개하면 됩니다.
api-catalog 관련 질문
/.well-known/api-catalog란 무엇인가요?
RFC 9727에서 조직의 API 목록을 기계가 읽을 수 있는 형식으로 제공하도록 정의한 경로입니다. 이 파일은 각 API에서 해당 설명, 문서, 상태 페이지로 연결되는 JSON linkset입니다. 클라이언트는 이 경로에서 파일을 직접 찾거나 api-catalog 링크 관계를 통해 찾을 수 있습니다.
api-catalog에 필요한 Content-Type은 무엇인가요?
RFC 9727에 따르면 application/linkset+json을 사용해야 하며, https://www.rfc-editor.org/info/rfc9727 프로필 매개변수를 포함하는 것이 좋습니다. 이 페이지의 nginx 설정 블록은 미디어 유형과 Link 헤더를 설정합니다. 서버 설정에서 지원한다면 프로필 매개변수는 직접 추가하세요.
카탈로그를 공개하려면 OpenAPI 파일이 필요한가요?
아니요. 이 생성기에서는 각 항목에 API 기본 URL만 있으면 됩니다. 설명, 문서, 상태 페이지 링크는 선택 사항입니다. OpenAPI 설명이 있으면 클라이언트가 문서를 읽지 않고도 엔드포인트를 파악할 수 있으므로, 파일이 있다면 추가하세요.
api-catalog와 llms.txt는 어떻게 다른가요?
api-catalog는 API를 호출하는 소프트웨어를 위해 API를 JSON 링크로 나열하는 IETF RFC입니다. llms.txt는 문서를 읽는 언어 모델을 대상으로 페이지를 Markdown 색인으로 정리하자는 제안입니다. 두 표준은 용도가 겹치지 않으므로 둘 다 공개할 수 있습니다.