OpenAPI 스키마를 사용한 요청 유효성 검사
이 참조 문서에서는 OpenAPI 스키마가 무엇인지, 어떻게 작동하는지, 그리고 Braze REST API 엔드포인트로 보내는 요청이 올바르게 구성되었는지 전송 전에 확인하는 방법을 설명합니다.
모든 Braze REST API 엔드포인트 페이지에는 OpenAPI 사양에서 생성된 인터랙티브 참조가 표시됩니다. 각 사양에는 스키마가 포함되어 있습니다. 스키마는 엔드포인트가 수락하고 반환하는 데이터에 대한 정확하고 기계가 읽을 수 있는 설명입니다. 이 스키마를 사용하여 요청의 유효성을 검사할 수 있으므로, 실패한 API 호출로 인해 문제를 발견하는 대신 자체 도구에서 구조적 실수를 미리 포착할 수 있습니다.
Braze가 이러한 사양을 게시하는 방법과 해당 사양이 지원하는 다른 워크플로에 대한 전반적인 개요는 Braze OpenAPI 사양 사용하기를 참조하세요.
OpenAPI 스키마란
스키마는 엔드포인트의 데이터에 대한 계약입니다. OpenAPI 문서에서 Schema Object는 엔드포인트가 사용하는 각 필드를 정의하며, 여기에는 필드의 이름, 데이터 유형, 필수 여부, 허용 값, 그리고 중첩된 객체와 배열의 구조가 포함됩니다.
OpenAPI 스키마는 JSON 데이터의 형태를 설명하기 위해 널리 채택된 표준인 JSON Schema를 기반으로 합니다. 이 계약은 표준적이고 기계가 읽을 수 있는 형식으로 표현되므로, 필드를 수동으로 확인하는 대신 기성 도구를 사용하여 페이로드를 스키마에 대해 검증할 수 있습니다. 관련 개념에 대해 자세히 알아보려면 Learn OpenAPI 및 Understanding JSON Schema를 참조하세요.
스키마 작동 방식
스키마는 작은 구성 요소 집합을 사용하여 데이터를 설명합니다. 가장 일반적으로 사용되는 요소는 다음과 같습니다.
- 타입.
string,integer,number,boolean,array,object등 값의 데이터 유형입니다. Swagger 설명서의 Data types를 참조하세요. - 필수 필드. 데이터가 유효하려면 반드시 포함되어야 하는 속성 목록입니다.
- 제약 조건. 허용되는 값의 열거형(
enum), 형식(format, 예:date-time), 문자열 패턴, 최솟값 및 최댓값 등 값이 가질 수 있는 범위를 제한하는 규칙입니다. - 중첩 구조. 객체는 다른 객체를 포함할 수 있고, 배열은 포함하는 항목의 스키마를 선언하므로 스키마로 깊이 구조화된 페이로드를 설명할 수 있습니다.
유효성 검사기는 이러한 규칙을 읽고 데이터를 규칙과 비교합니다. 필수 필드가 누락되었거나 값의 유형이 잘못되었거나 값이 허용된 범위를 벗어나는 경우, 유효성 검사기가 구체적인 문제를 보고합니다. JSON Schema 사양에서 이 유효성 검사 동작에 대해 자세히 정의하고 있습니다.
스키마가 유효한 요청을 정의하는 방식
요청 본문을 받는 엔드포인트의 경우, 명세의 요청 본문 스키마는 유효한 페이로드가 어떤 형태여야 하는지를 정확하게 설명합니다. 많은 Braze 엔드포인트는 사용자 식별자, 메시징 객체, 오디언스 필터 등 동일한 요청 구조를 재사용합니다. 이러한 공유 구조에 대한 필드별 참고 자료는 오브젝트 및 필터를 확인하세요. 문자열 external_id와 정수 points가 필수이며, points는 음수가 될 수 없는 간단한 스키마 예시를 살펴보겠습니다:
{
"type": "object",
"required": ["external_id", "points"],
"properties": {
"external_id": { "type": "string" },
"points": { "type": "integer", "minimum": 0 }
}
}
이 스키마를 충족하는 페이로드는 유효합니다:
{ "external_id": "user-123", "points": 50 }
다음 각 페이로드는 유효하지 않으며, 검증기가 그 이유를 설명합니다:
{ "points": 50 }는 필수 필드인external_id를 누락했습니다.{ "external_id": "user-123", "points": "50" }는points를 정수가 아닌 문자열로 전송합니다.{ "external_id": "user-123", "points": -5 }는minimum제약 조건을 위반하는 값을 전송합니다.
스키마를 먼저 읽으면, 단 한 번의 호출을 하기 전에 어떤 필드를 전송해야 하는지, 각 값이 어떤 타입이어야 하는지, 어떤 값이 허용되는지를 미리 파악할 수 있습니다.
스키마에 대한 요청 유효성 검증
엔드포인트의 스키마에 대해 페이로드의 유효성을 검증하려면 다음 단계를 따르세요.
- 원하는 엔드포인트에 대한 스펙을 다운로드합니다. 각 스펙은
https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yaml형식의 안정적인 공개 URL에서 이용할 수 있습니다. - 스펙에서 요청 본문 스키마를 추출합니다.
- JSON 스키마 유효성 검증기를 사용하여 해당 스키마에 대해 페이로드의 유효성을 검증합니다. JavaScript용 Ajv 또는 사용 중인 언어에 맞는 JSON Schema tools 목록에서 다른 라이브러리를 활용할 수 있습니다.
- 유효성 검증기에서 누락, 유형 불일치 또는 범위 초과로 표시된 필드를 수정한 후 요청을 전송합니다.
Spectral과 같은 도구를 사용하여 전체 스펙을 린트하고 유효성을 검증하거나, OpenAPI Generator를 사용하여 타입이 지정된 요청 모델을 생성하면 코드가 처음부터 유효한 페이로드를 생성하도록 할 수 있습니다. 이러한 스펙을 활용하는 단계별 워크플로는 스키마 사용 방법을 참조하세요.
스키마 유효성 검사가 중요한 이유
스키마에 대해 요청의 유효성을 검사하면 다음과 같은 이점이 있습니다.
- 오류를 조기에 발견할 수 있습니다. API 호출이 거부된 후가 아니라, 자체 환경에서 누락되거나 잘못 입력된 필드를 사전에 찾을 수 있습니다.
- 실패한 호출을 줄일 수 있습니다. 처음부터 올바른 형식의 요청을 보내면 재시도와 문제 해결 횟수가 줄어듭니다.
- 자신 있게 통합할 수 있습니다. 요청 형식을 수동으로 복사하는 대신 단일 머신 리더블 계약을 기반으로 작업할 수 있습니다.
- 검사를 자동화할 수 있습니다. 테스트 또는 CI 파이프라인에 유효성 검사를 추가하면 코드가 변경되더라도 통합이 올바르게 유지됩니다.