Pulumi Cloud REST API Docs, 이제 OpenAPI에서 생성됨
Source: Pulumi Blog
왜 중요한가
이전 REST API 레퍼런스는 손으로 직접 작성한 페이지들의 집합이었습니다. 새로운 엔드포인트가 추가되거나, 매개변수 이름이 바뀌거나, 응답 형태가 수정될 때마다 해당 문서에 대한 PR이 필요했고, 실제로는 페이지가 점점 어긋나게 되었습니다. 작은 불일치가 쌓이면서 매개변수가 누락되거나, 요청 형태가 오래되었거나, 스키마가 API가 반환하는 내용과 맞지 않는 경우가 발생했습니다. API가 성장함에 따라 문서를 동기화할 수 있는 지속 가능한 해결책이 필요했습니다.
OpenAPI 사양에서 레퍼런스를 생성하면 이러한 격차가 해소됩니다. API에 변경이 배포되면, 다음에 문서를 빌드할 때 자동으로 문서가 업데이트됩니다.
새로운 점
/docs/reference/cloud-rest-api/ 에 있는 레퍼런스에는 이제 다음이 포함됩니다:
- 필요한 정보를 더 빠르게 찾기 – 엔드포인트가 제품 영역(스택, 배포, 환경, 조직, 레지스트리, 인사이트, AI, 워크플로우 등)별로 그룹화되어 있어 작업 중인 API 부분으로 바로 이동할 수 있습니다.
- 완전한 요청 및 응답 상세 정보 – 모든 엔드포인트가 매개변수, 요청 본문, 반환되는 정확한 형태를 문서화하므로, 추측 없이 무엇을 보내고 무엇을 기대해야 하는지 알 수 있습니다.
- 관련 타입 간 원클릭 탐색 – 응답이 다른 객체를 참조할 때, 타입 이름이 링크가 됩니다. 긴 API 레퍼런스 페이지를 스크롤하는 대신 클릭하여 전체 정의를 확인할 수 있습니다.
에이전트를 위한 활용 가능성
레퍼런스를 사양과 동기화하는 것은 인간에게만 편리한 것이 아니라, 문서를 읽고 대신 API를 호출하는 AI 에이전트에게도 신뢰성을 제공합니다. 손으로 작성된 레퍼런스를 읽는 에이전트는 6개월 전에 이름이 바뀐 매개변수를 보거나, API가 이제 반환하는 필드를 놓칠 수 있어 호출이 조용히 실패하거나 디버깅이 어려운 상황이 발생합니다. 레퍼런스가 사양에서 자동 생성되면, 에이전트는 현재 API가 실제로 허용하는 내용을 기반으로 작업합니다.
예를 들어 새로운 팀을 온보딩하고 Pulumi Cloud에서 접근 권한을 설정해야 한다고 가정해 보세요. 에이전트에게 REST API 레퍼런스를 가리키고 다음을 요청합니다:
sre‑on-call팀을 생성합니다.- 네 명의 멤버를 추가합니다.
- 세 개의 스택에 대해 관리자 권한을 부여합니다.
에이전트는 팀, 멤버십, 스택‑권한 엔드포인트를 순차적으로 탐색하고 올바른 호출 순서를 구성해 실행합니다.
대량 감사 및 정리 작업에도 같은 패턴이 적용됩니다. 조직 내 모든 스택 중 최근 업데이트가 없는 스택을 찾아 stale 태그를 붙으라고 에이전트에 요청하면, 응답 스키마가 실제와 일치하기 때문에 페이지네이션을 올바르게 수행할 수 있습니다. 이전에도 기술적으로 가능했지만, 이제는 훨씬 더 신뢰할 수 있게 되었습니다.
동일한 URL, 기존 링크는 그대로 작동
생성된 문서는 이전 레퍼런스와 동일한 URL인 /docs/reference/cloud-rest-api/ 에 위치합니다. 북마크, 블로그 링크, 검색 트래픽 모두 여전히 올바른 페이지로 이동합니다. 페이지가 수정, 이름 변경, 이동된 경우에 대비해 리디렉션이 설정되어 있습니다.
직접 사용해 보기
새로운 REST API 레퍼런스에 접속해 카테고리별로 탐색해 보세요. 각 페이지는 사용되는 요청 및 응답 객체 스키마로 연결됩니다.
잘못된 부분을 발견하면 가장 가능성이 높은 원인은 OpenAPI 사양 자체입니다 — pulumi/docs 에 이슈를 등록하면 원본을 추적해 수정하겠습니다. 태그 인트로스와 구조 개선을 위한 PR도 환영합니다. 질문과 피드백은 언제든지 Pulumi Community Slack 에서 환영합니다.