Braze OpenAPI 사양 사용하기
이 참고 문서에서는 Braze가 REST API 엔드포인트에 대한 OpenAPI 사양을 게시하는 방법과 해당 사양의 스키마를 사용하여 개발 워크플로를 가속화하는 방법을 설명합니다.
각 Braze REST API 엔드포인트 페이지는 OpenAPI 사양에서 생성된 인터랙티브 레퍼런스를 표시합니다. 레퍼런스에는 엔드포인트의 파라미터, 요청 본문, 응답 스키마 및 예시 응답이 일관되고 구조화된 형식으로 표시됩니다. 모든 사양은 다운로드하여 자체 도구에서 직접 사용할 수 있는 기계 판독 가능 파일이기도 합니다.
각 엔드포인트 페이지의 레퍼런스는 읽기 전용입니다. 설명서 사이트에서 실시간 요청을 전송하지 않습니다. 엔드포인트를 호출하려면 생성된 cURL 예제를 복사하거나 스키마 사용 방법에 설명된 대로 다운로드한 사양을 자체 클라이언트에서 사용하세요.
사양 찾기
REST API 엔드포인트 페이지에서 엔드포인트 레퍼런스 섹션을 찾으세요. 원본 사양을 열려면 해당 섹션의 사양 다운로드 옵션을 사용하세요. 각 파일은 다음 형식의 안정적인 공개 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 스키마 유효성 검사기 또는 사용 중인 언어의 라이브러리를 사용하여 해당 스키마에 대해 페이로드의 유효성을 검사합니다.
- 유효성 검사기가 누락, 잘못된 유형 또는 범위 초과로 표시한 필드를 수정합니다.
Postman 또는 다른 클라이언트로 가져오기
미리 채워진 요청과 인라인 필드 설명을 얻으려면:
- Postman에서 Import를 선택한 다음 다운로드한 사양 파일을 선택합니다.
- Postman이 엔드포인트, 파라미터 및 예시 값이 포함된 컬렉션을 생성합니다.
- REST API 키와 대상 REST 엔드포인트를 추가한 다음 요청을 전송합니다.
엔드포인트 모킹
실시간 통합 코드를 작성하기 전에 엔드포인트에 대해 빌드하려면:
- Prism 같은 모킹 도구에 사양을 로드합니다.
- 모의 서버를 시작하면 사양의 스키마와 일치하는 응답을 반환합니다.
- 개발하는 동안 애플리케이션을 모의 서버로 지정하고, 준비가 되면 실시간 REST 엔드포인트로 전환합니다.