Braze OpenAPI 사양 사용하기
이 참고 문서에서는 Braze가 REST API 엔드포인트에 대한 OpenAPI 사양을 게시하는 방법과 해당 사양의 스키마를 사용하여 개발 워크플로를 가속화하는 방법을 설명합니다.
각 Braze REST API 엔드포인트 페이지는 OpenAPI 사양에서 생성된 인터랙티브 레퍼런스를 표시합니다. 레퍼런스에는 엔드포인트의 파라미터, 요청 본문, 응답 스키마 및 예시 응답이 일관되고 구조화된 형식으로 표시됩니다. 모든 사양은 다운로드하여 자체 도구에서 직접 사용할 수 있는 기계 판독 가능 파일이기도 합니다.
각 엔드포인트 페이지의 레퍼런스는 읽기 전용입니다. 설명서 사이트에서 실시간 요청을 전송하지 않습니다. 엔드포인트를 호출하려면 생성된 cURL 예제를 복사하거나 스키마 사용 방법에 설명된 대로 다운로드한 사양을 자체 클라이언트에서 사용하세요.
스펙을 찾는 방법
모든 REST API 엔드포인트 페이지에서 Endpoint reference 섹션을 찾을 수 있습니다. 해당 섹션의 스펙 다운로드 옵션을 사용하면 원시 사양 파일을 열 수 있습니다. 각 파일은 다음 형식의 안정적인 공개 URL에 위치합니다:
https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yaml
각 파일은 하나의 엔드포인트에 대한 독립적인 단일 OpenAPI 3 문서입니다. 이 문서에는 엔드포인트가 수신하고 반환하는 데이터의 정확한 구조를 설명하는 요청 및 응답 스키마가 포함되어 있습니다.
스키마가 유용한 이유
스키마는 엔드포인트에 대한 구조화된 계약입니다. 각 필드의 이름, 데이터 유형, 필수 여부, 허용 값, 그리고 객체가 어떻게 중첩되는지를 정의합니다. 이 계약은 기계가 읽을 수 있는 형식이므로, 요청과 응답 구조를 직접 복사하는 대신 스키마를 활용할 수 있습니다. 여러 엔드포인트에서 공유하는 재사용 가능한 객체와 필터에 대해서는 객체 및 필터를 참고하세요. 스키마를 통해 다음과 같은 작업이 가능합니다:
- 클라이언트 코드 및 SDK 생성. 선호하는 언어로 타입이 지정된 요청 및 응답 모델 또는 전체 클라이언트 라이브러리를 생성하여 요청 본문을 직접 작성하지 않아도 됩니다.
- 요청 및 응답 유효성 검사. 페이로드를 전송하기 전에 스키마와 대조하여 검증하고, 응답이 예상과 일치하는지 확인하여 통합 버그를 조기에 발견할 수 있습니다.
- API 모킹. 스펙을 기반으로 모의 서버를 구축하여 실시간 통합 코드를 작성하기 전에 Braze 엔드포인트를 대상으로 개발하고 테스트할 수 있습니다.
- API 클라이언트로 가져오기. Postman이나 Insomnia 같은 도구에 스펙을 로드하면 미리 채워진 요청, 파라미터 설명, 자동완성 기능을 활용할 수 있습니다.
- 통합 상태 동기화 유지. 저장된 스펙 사본을 현재 버전과 비교하여 필드가 추가되거나 변경된 시점을 감지하고, 안심하고 통합을 업데이트할 수 있습니다.
스키마 사용 방법
다음 안내에서는 엔드포인트 페이지에서 스펙 파일을 이미 다운로드했다고 가정합니다.
스펙 보기 및 탐색
스펙을 구조화된 인터랙티브 뷰로 읽으려면 아무 OpenAPI 뷰어나 사용하세요:
- 원하는 엔드포인트의 스펙 파일을 다운로드합니다.
- Swagger Editor 또는 유사한 뷰어를 엽니다.
- 파일을 붙여넣거나 업로드하여 오퍼레이션, 파라미터, 정의된 모든 스키마를 탐색합니다.
클라이언트 또는 모델 생성
스키마를 사용 중인 언어의 타입이 지정된 코드로 변환하려면 OpenAPI 생성기를 사용하세요:
- OpenAPI Generator와 같은 생성기를 설치합니다.
- 생성기가 스펙 파일을 가리키도록 설정하고 대상 언어를 선택합니다.
- 요청 본문을 수동으로 작성하는 대신, 생성된 요청 및 응답 모델 또는 전체 클라이언트를 애플리케이션에서 사용합니다.
페이로드 유효성 검사
요청 본문이 엔드포인트의 계약에 맞는지 전송 전에 확인하려면:
- 스펙에서 요청 본문 스키마를 추출합니다.
- JSON Schema 유효성 검사 도구 또는 사용 중인 언어의 라이브러리를 사용하여 해당 스키마에 대해 페이로드의 유효성을 검사합니다.
- 유효성 검사 도구가 누락, 타입 불일치 또는 범위 초과로 표시한 필드를 수정합니다.
Postman 또는 다른 클라이언트로 가져오기
미리 채워진 요청과 인라인 필드 설명을 얻으려면:
- Postman에서 Import를 선택한 다음 다운로드한 스펙 파일을 선택합니다.
- Postman이 엔드포인트, 파라미터 및 예시 값이 포함된 컬렉션을 생성합니다.
- REST API 키와 대상 REST 엔드포인트를 추가한 다음 요청을 보냅니다.
엔드포인트 모킹
실시간 통합 코드를 작성하기 전에 엔드포인트를 기반으로 개발하려면:
- Prism과 같은 모킹 도구에 스펙을 로드합니다.
- 모의 서버를 시작하면 스펙의 스키마에 맞는 응답을 반환합니다.
- 개발하는 동안 애플리케이션이 모의 서버를 가리키도록 설정한 다음, 준비가 되면 실시간 REST 엔드포인트로 전환합니다.