Braze OpenAPI 사양 사용하기
이 참고 문서에서는 Braze가 REST API 엔드포인트에 대한 OpenAPI 사양을 게시하는 방법과 해당 사양의 스키마를 사용하여 개발 워크플로를 가속화하는 방법을 설명합니다.
각 Braze REST API 엔드포인트 페이지는 OpenAPI 사양에서 생성된 인터랙티브 레퍼런스를 표시합니다. 레퍼런스에는 엔드포인트의 파라미터, 요청 본문, 응답 스키마 및 예시 응답이 일관되고 구조화된 형식으로 표시됩니다. 모든 사양은 다운로드하여 자체 도구에서 직접 사용할 수 있는 기계 판독 가능 파일이기도 합니다.
레퍼런스에서 Test Request를 사용하여 요청을 보낼 수 있습니다. Bearer Token 필드에 REST API 키를 입력하고 서버 목록에서 REST 엔드포인트를 선택하세요. 요청은 워크스페이스에서 실행되며 실제 데이터를 변경하므로 테스트 워크스페이스용 키를 사용하세요. PUT, PATCH 또는 DELETE를 사용하는 엔드포인트는 설명서 사이트에서 요청을 보낼 수 없으므로 Test Request가 표시되지 않습니다. 이러한 엔드포인트의 경우 생성된 cURL 예제를 복사하거나 스키마 사용 방법에 설명된 대로 다운로드한 사양을 자체 클라이언트에서 사용하세요.
사양을 찾을 수 있는 위치
REST API 엔드포인트 페이지에서 레퍼런스의 Download OpenAPI Document를 선택하거나, 페이지 하단의 다운로드 링크를 사용하세요. 각 파일은 다음 형식의 고정된 공개 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에서 가져오기를 선택한 다음, 다운로드한 사양 파일을 선택합니다.
- Postman이 엔드포인트, 해당 파라미터, 예시 값이 포함된 컬렉션을 생성합니다.
- REST API 키와 대상 REST 엔드포인트를 추가한 다음 요청을 보냅니다.
엔드포인트 모킹
실시간 통합 코드를 작성하기 전에 엔드포인트를 기준으로 개발하려면 다음을 수행하세요.
- Prism과 같은 모킹 도구에 사양을 로드합니다.
- 사양의 스키마와 일치하는 응답을 반환하는 모의 서버를 시작합니다.
- 개발하는 동안 애플리케이션이 모의 서버를 가리키도록 설정한 다음, 준비가 되면 실시간 REST 엔드포인트로 전환합니다.