Pulsar REST API와 OpenAPI 스펙

REST API(REpresentational State Transfer Application Programming Interface)는 REST 표준에 따라 HTTP 요청으로 데이터를 GET, PUT, POST, DELETE 하면서 애플리케이션 소프트웨어를 구축·통합하기 위한 정의와 프로토콜의 집합이에요. 쉽게 말하면 두 시스템 사이에서 표준 메서드로 특정 형식의 데이터를 요청·반환하는 원격 호출의 모음이죠. Pulsar는 정보를 조회하거나 작업을 수행하도록 상호작용할 수 있는 다양한 REST API를 제공해요.

출처: 문서

본문

REST API로 자동화하기 (Automate with the REST API)

pulsar-admin CLI와 Java 관리 클라이언트는 모두 REST API의 클라이언트예요. 이들이 하는 모든 일은 브로커(또는 브로커 앞의 프록시)에 대한 HTTP 요청이에요. 따라서 HTTP를 말할 수 있는 어떤 도구든 JVM을 시작하지 않고도 Pulsar 클러스터를 제어할 수 있어요. 다른 언어로 작성된 자동화, 운영자·컨트롤러, Kubernetes 클러스터 안에서 실행되는 스크립트에 적합한 방법이에요. 브로커의 웹 서비스 포트에 대한 curl이 pulsar-admin 호출보다 더 가볍기 때문이죠.

Get started 페이지에서 curl로 엔드포인트를 호출하는 방법(인증 포함)을 보여줘요. 대부분의 엔드포인트는 JSON을 받거나 아무것도 받지 않아요. 패키지를 업로드하는 엔드포인트(함수·소스·싱크 생성/업데이트)는 구성 부분이 application/json 콘텐츠 타입을 반드시 담아야 하는 multipart/form-data 요청을 받아요. 실제 curl 예제는 Create a function을 참고해요. 예를 들어 다음 요청은 번들을 선택한 브로커로 언로드하고 자동 로드 셰딩(load shedding)을 일시 중지하는 것으로, 브로커 롤링 업그레이드에서 사용하는 두 작업이에요.

# equivalent to: pulsar-admin namespaces unload my-tenant/my-namespace --bundle 0x00000000_0x08000000 --destinationBroker broker-2.example.com:8080
curl -X PUT "http://broker.example.com:8080/admin/v2/namespaces/my-tenant/my-namespace/0x00000000_0x08000000/unload?destinationBroker=broker-2.example.com:8080"
# equivalent to: pulsar-admin brokers update-dynamic-config --config loadBalancerSheddingEnabled --value false
curl -X POST "http://broker.example.com:8080/admin/v2/brokers/configuration/loadBalancerSheddingEnabled/false"

OpenAPI 스펙 (OpenAPI specifications)

Pulsar 5.0부터 REST API는 매 릴리스마다 브로커 소스 코드에서 생성되어 이 사이트와 함께 게시되는 OpenAPI 3 문서로 설명돼요. 각 Pulsar 버전은 고유한 디렉터리를 가져요. https://pulsar.apache.org/openapi/<version>/ (이 문서가 다루는 버전은 /openapi/5.0.0-M2/, master 디렉터리는 개발 브랜치를 따름), REST API 카테고리마다 하나의 문서가 있어요.

예를 들어 Pulsar 5.0.0-M2의 admin API는 https://pulsar.apache.org/openapi/5.0.0-M2/openapi.json이에요. 버전 디렉터리 루트의 이 문서는 현재 /admin/v2 admin API를 설명해요. v1 admin API는 더 이상 존재하지 않으므로 별도의 v1 문서는 없어요. functions, sources, sinks, packages, transactions API는 각자의 /admin/v3 문서로만 설명되며 admin 문서에는 포함되지 않아요. 따라서 이들을 관리하는 클라이언트는 openapi.json 외에도 그 문서들이 필요해요. v2/와 v3/ 하위 디렉터리에는 같은 문서의 바이트 단위로 동일한 복사본이 REST API base path별로 그룹화되어 있어요(v2/에는 /admin/v2, /lookup/v2, v3/에는 /admin/v3). 이들은 더 오래된 API 버전도 다른 OpenAPI 버전도 아니므로 편한 경로를 쓰면 돼요. 5.0 이전 릴리스는 대신 https://pulsar.apache.org/swagger/<version>/ 아래에 Swagger 2.0 문서를 게시해요.

이 스펙들은 위에 나열된 REST API 레퍼런스 페이지를 렌더링하는 바로 그 문서들이에요. 따라서 레퍼런스 페이지에서도 버전의 스펙을 내려받을 수 있어요. Postman이나 Insomnia 같은 도구가 직접 가져와서 API를 탐색·테스트할 수 있어요.

스펙 다운로드 (Download the specifications)

개발 브랜치와 유지보수 릴리스 라인의 최신 릴리스에 해당해요. 더 오래된 릴리스는 같은 디렉터리 구조 아래 문서를 유지해요.

스펙에서 클라이언트 생성 (Generate a client from the specification)

OpenAPI 3 문서가 있으면 대부분의 언어에서 admin API용 클라이언트 라이브러리를 손으로 작성하는 대신 생성할 수 있어요. OpenAPI Generator는 Go, Python, TypeScript, Rust, C#, Kotlin, Java를 포함한 50개 이상의 클라이언트 제너레이터를 지원해요. 예를 들어 이 문서가 다루는 버전의 admin API용 Python 클라이언트를 생성하려면:

openapi-generator-cli generate \
    -i https://pulsar.apache.org/openapi/5.0.0-M2/openapi.json \
    -g python \
    -o ./pulsar-admin-python

생성된 클라이언트는 브로커의 웹 서비스 URL을 base path로 삼고, 인증 제공자의 인증 헤더(예: bearer 토큰)를 추가할 수 있게 해줘요. Pulsar를 업그레이드할 때 새 엔드포인트·파라미터가 생기므로 다시 생성하세요. REST API는 버전 간에 하위 호환성을 유지하므로, 더 오래된 스펙에서 생성한 클라이언트도 최신 브로커에서 계속 동작해요.

함수, 소스, 싱크 생성 (Create functions, sources and sinks)

함수·소스·싱크를 생성하거나 업데이트하는 것은 admin API 중 평범한 JSON 요청이 아닌 유일한 부분이에요. 엔드포인트는 구성이 JSON 파트(반드시 application/json 콘텐츠 타입을 담아야 함)이고 패키지가 파일 파트 또는 패키지 URL인 multipart/form-data 요청을 받아요. 내장 함수·커넥터의 경우 구성에 builtin://<name>을 쓰기도 해요. 실제 curl 예제와 세부 사항은 Create a function을 참고하세요. 소스와 싱크는 sourceConfig 또는 sinkConfig 파트로 같은 형태를 사용해요.

HTTP로 메시지 생성 (Produce messages over HTTP)

브로커는 같은 웹 서비스 포트에서 HTTP로 메시지도 받아요. POST /topics/persistent/{tenant}/{namespace}/{topic} (파티셔닝된 토픽의 한 파티션이라면 /partitions/{n})에 메시지를 담은 JSON 본문과, 선택적으로 인코딩에 쓸 스키마를 보내면 돼요. 이는 클라이언트 라이브러리를 쓸 수 없는 애플리케이션을 위한 데이터 경로(data-path) 엔드포인트로, admin API의 일부가 아니며 위 OpenAPI 문서에도 포함되지 않아요. 클라이언트 라이브러리 아래 Pulsar REST 문서에 설명돼 있어요.

더 알아보기 (Learn more)

curl로 관리 엔드포인트를 호출하는 방법은 Get started에서 확인해요.
인증 제공자 설정은 Security overview 문서를 참고해요.
함수 생성을 위한 실제 curl 예제는 Create a function을 봐요.
HTTP로 메시지를 생성하고 싶다면 Pulsar REST 문서를 살펴봐요.

Pulsar REST API와 OpenAPI 스펙