Arazzo 사양은 API 워크플로우, 즉 하나 이상의 API를 호출하여 목표를 달성하는 정렬된 단계를 설명하는 OpenAPI 이니셔티브 표준입니다. 단일 OpenAPI 사양이 단일 API 표면(경로, 작업, 스키마, 보안)에 초점을 맞추는 반면, Arazzo 설명은 해당 API 주변의 조율, 즉 각 단계에 필요한 입력, 단계 간의 종속성, 진행 상황을 표시하는 성공 기준, 그리고 다음 단계로 전달할 출력을 포착합니다. 요컨대, Arazzo는 개발자가 이미 코드에서 구축하고 테스터가 이미 스위트에서 자동화하는 '이것을 하고, 저것을 하는' 시나리오를 모델링하는 공식적이고 기계 판독 가능한 방법입니다.
실제로 대부분의 팀은 이미 워크플로우를 다루고 있습니다:
- 로그인, 프로필 가져오기, 환경설정 업데이트
- 장바구니 생성, 품목 추가, 총액 계산, 결제, 확인
- 신청서 제출, 상태 폴링, 문서 업로드, 승인 받기
Arazzo는 이러한 시퀀스에 공통 언어를 제공합니다. 형식은 JSON 또는 YAML입니다. 최상위 객체는 Arazzo 버전(arazzo: 1.0.x), 메타데이터(info), 소스 API 설명 목록(sourceDescriptions, 종종 이미 유지 관리하는 OpenAPI 사양 파일), 워크플로우 목록(workflows), 그리고 components에 재사용 가능한 요소를 선언합니다. 각 워크플로우에는 inputs(이름 및 유형), 정렬된 steps(단계 ID 포함), 참조된 API 호출에 주입되는 선택적 parameters, successCriteria($statusCode == 200과 같은 간단한 단언), 그리고 이후 단계에서 사용할 수 있는 outputs가 포함됩니다.
이것이 API 설계 및 API 사양에 왜 중요할까요?
- 추측을 줄여줍니다. 각 엔드포인트가 개별적으로 무엇을 하는지뿐만 아니라 API가 어떻게 사용되어야 하는지를 보여줍니다.
- 인수인계를 개선합니다. 제품, 백엔드, 프론트엔드 및 QA 팀이 모두 동일하고 간결한 워크플로우 설명을 읽습니다.
- 도구를 가능하게 합니다. Arazzo는 기계 판독 가능하므로 편집기, 린터, 목업 도구 및 실행기가 이를 사용할 수 있습니다.
- 변경을 지원합니다. 엔드포인트가 진화하더라도 워크플로우는 소비자가 정상 경로에 맞춰지도록 유지합니다.
Arazzo는 OpenAPI 사양을 대체하지 않습니다. 오히려 그 위에 계층을 추가합니다. Arazzo는 하나 이상의 OpenAPI 문서를 가리키고(sourceDescriptions를 통해) 이를 종단 간 흐름으로 구성합니다. 이러한 역할을 명확히 구분하면 혼동을 피할 수 있습니다: OpenAPI는 API를 설명하고, Arazzo는 하나 이상의 API를 사용하여 작업을 수행하는 방법을 설명합니다.
Arazzo 사양 객체 내부
간단한 안내를 통해 Arazzo 파일을 자신 있게 읽고 작성하는 데 도움이 될 것입니다. 주요 섹션은 다음과 같습니다:
arazzo: Arazzo 버전, 예를 들어1.0.1.info: 워크플로우 설명의 제목, 요약, 설명 및 버전.sourceDescriptions: 워크플로우에 사용되는 소스 사양 목록. 각 항목에는name,type(예:openapi), 그리고 게시된 OpenAPI 사양과 같은 소스에 대한url이 있습니다.workflows: 워크플로우 객체 배열. 각 객체에는workflowId,summary,description,inputs,steps, 그리고 워크플로우 수준의outputs가 포함됩니다.components: 워크플로우 설명에 사용되는 재사용 가능한 스키마.
일반적인 단계는 다음을 포함합니다:
stepId:loginStep또는getPetStep과 같은 고유 레이블.- 소스 OpenAPI 사양을 가리키는
operationId또는operationPath를 통한 API 작업 참조. parameters: 요청에 주입되는 값으로, 종종 이전inputs또는 단계outputs에서 가져옵니다.successCriteria:$statusCode == 200과 같은 간단한 부울 검사.outputs: 헤더 또는 본문에서 캡처된 변수, 예:tokenExpires: $response.header.X-Expires-After또는sessionToken: $response.body.
작업 분담을 명확히 하기 위해 다음 사고 모델을 사용하십시오:
관심사 | OpenAPI 사양 | Arazzo 사양 |
단일 API 표면 설명 | 경로, 작업, 스키마, 보안 | OpenAPI 문서 참조 |
비즈니스 흐름 설명 | 범위 외 | 워크플로우, 단계, 입력, 출력 |
기계 판독성 | 예 | 예 |
인간 판독성 | 예 | 예 (더 짧은 설명) |
도구 | 유효성 검사기, 코드 생성, 목업 | 실행기, 워크플로우 문서, 연결 |
Arazzo 사양이 OpenAPI 사양을 보완하는 방법
Arazzo와 OpenAPI는 API 설계에서 잘 조화를 이룹니다. OpenAPI는 서비스에 대한 공식 계약으로 남아 있습니다. Arazzo는 서비스를 함께 연결하는 방법에 대한 플레이북이 됩니다. 둘 다 게시하면 소비자는 '왜'와 '어떻게'를 이해하게 됩니다:
- 비즈니스 여정의 맥락에서 각 엔드포인트가 존재하는 이유
- 순서대로 호출하는 방법, 무엇을 전달하고 무엇을 받을지
좋은 관행:
sourceDescriptions가 안정적이고 버전이 지정된 OpenAPI 사양 URL을 가리키도록 유지하십시오.workflowId와stepId를 명확하게 명명하십시오; 나중에 검색할 코드처럼 다루십시오.- 단언을 간단하고 명확하게 유지하십시오; 이를 살아있는 승인 기준으로 사용하십시오.
- 사용할 출력만 캡처하십시오. 짧을수록 유지 관리가 쉽습니다.
실제 API 설계 시나리오에 Arazzo 사양을 적용한 예시
세 가지 일반적인 흐름으로 이 아이디어를 확고히 해봅시다. 간단하게 유지하고 거대한 페이로드는 피하겠지만, Arazzo의 가치는 여전히 보여줄 것입니다.
1. 사용자 로그인 + 사용 가능한 항목 목록
- 입력:
username,password - 단계:
loginUser($statusCode == 200일 때 성공), 이어서status=available쿼리와Authorization: $steps.loginUser.outputs.sessionToken헤더를 사용하여getItems - 출력:
$response.body에서availableItems
2. 결제 및 대금 청구
- 입력:
cartId,paymentMethod - 단계:
getCartTotals→createPaymentIntent→confirmPayment - 단계 사이에 총액과 클라이언트 시크릿 전달
- 각 단계에서의 단언 (
$statusCode == 200및$.status == "confirmed"와 같은 필드 확인)
3. 신청서 제출 및 폴링
- 입력:
appPayload - 단계:
submitApplication→pollStatus가$.state in ["APPROVED","REJECTED"]가 될 때까지 반복 - 출력:
decision및reason
Arazzo 설명에서 이들은 짧은 스크립트처럼 읽힙니다. 엔지니어, QA, 기술 작가 및 파트너 모두 신속하게 스캔할 수 있습니다. 예시를 작성할 때 몇 가지 실용적인 팁:
- OpenAPI 사양을 제어하는 경우
operationId를 선호하십시오; 경로 변경 시에도 안정적입니다. - 타사 OpenAPI에서 특정 경로를 정확히 지정해야 할 때
operationPath를 사용하십시오. - 나중에 더 나은 양식과 UI를 구현하기 위해
inputs를 유형화하고 문서화하십시오(문자열, 숫자, 객체). - 필요한 출력만 수집하십시오; 워크플로우를 두 번째 데이터 모델로 바꾸는 것을 피하십시오.
- 커밋 메시지를 작성하듯이 각 단계에 한 줄
summary를 추가하십시오.
이것이 API 설계와 API 사양이 함께 작동하는 데 어떻게 도움이 되는지:
- API 설계자는 여정과 엣지 케이스를 고려합니다; Arazzo는 이를 명확한 단계로 포착합니다.
- 개발자는 즉시 사용할 수 있는 승인 체크리스트를 얻습니다; 이는 불필요한 반복 작업을 줄입니다.
- 테스터는 워크플로우에서 직접 시나리오 테스트를 도출합니다; 재해석이 필요 없습니다.
마지막으로, Arazzo는 기계 판독 가능하므로 워크플로우를 사람이 읽을 수 있는 문서, CI 검사 또는 다이어그램으로 렌더링하는 작은 유틸리티를 구축할 수 있으며, 이를 OpenAPI 사양 저장소 가까이에 보관할 수 있습니다.
Apidog를 사용하여 API 설계 운영화: OpenAPI 사양 + Arazzo 정렬 워크플로우
Arazzo는 워크플로우를 설명합니다. OpenAPI는 API를 설명합니다. Apidog는 이 둘을 더 적은 노력으로 작동하는 제품으로 전환하는 데 도움을 줍니다. 현재 Arazzo가 Apidog 내에서 직접적인 저작 형식이 아니지만, 이 플랫폼은 Arazzo의 아이디어와 자연스럽게 연결되며 소비자가 신뢰하는 API를 설계, 테스트 및 게시하는 일상적인 도구를 제공합니다.
자신감 있는 설계 및 모델링:
- 경로, 작업, 스키마, 보안 및 예시에 대한 시각적 API 설계
- 엔드포인트, 전역 매개변수 및 재사용 가능한 구성 요소에 대한 일괄 관리
- 내장된 AI 지원 및 AI 기반 엔드포인트 준수 검사를 통해 팀의 API 설계 가이드라인에 대한 문서 품질 평가
더 빠른 개발 및 디버깅:
- 환경, 변수 및 기록을 갖춘 풍부한 요청 실행기
- 단계 기반 흐름을 반영하는 엔드포인트 케이스(시나리오 테스트): 변수 추출(JSONPath), 요청 연결 및 성공 단언
- 회귀를 조기에 발견하기 위한 데이터 기반 및 성능 테스트
사람과 AI가 사용할 수 있는 문서 게시:
- OpenAPI 사양과 동기화되는 실시간 대화형 문서
- 다섯 가지 접근 모드: 공개, 비밀번호, IP 허용 목록, 이메일 허용 목록, 사용자 지정 로그인
- LLM 친화적 기능: 모든 페이지에 마크다운 게시, llms.txt 생성, Cursor 또는 Cline과 같은 IDE 에이전트를 안내하는 MCP 활성화
배포 및 학습:
- 발견을 위해 공용 API를 API 허브에 게시
- 분석 및 피드백 루프를 사용하여 예시, 설명 및 테스트 커버리지 개선
Arazzo는 명확한 워크플로우를 제공합니다. Apidog는 해당 워크플로우를 중심으로 API를 형성, 검증 및 제시할 수 있는 플랫폼을 제공합니다. 그 결과는 더 나은 API 설계, 더 강력한 API 사양, 그리고 더 빠른 채택입니다.
결론
Arazzo 사양은 API 프로그램에 누락된 컨텍스트를 추가합니다: 실제 워크플로우를 간결하고 기계 판독 가능한 방식으로 문서화합니다. 팀은 호출 순서, 입력 또는 성공 신호를 추측할 필요가 없습니다. 이를 OpenAPI 사양과 결합하면 이제 계약과 플레이북을 모두 소유하게 됩니다. 이해 관계자는 의도를 이해하고, 도구는 아이디어에서 작동하는 소프트웨어까지의 경로를 자동화할 수 있습니다.
이러한 문서를 신뢰할 수 있는 소프트웨어로 전환하려면 좋은 API 설계 습관을 운영화하는 플랫폼을 채택하십시오. Apidog는 엔드포인트를 모델링하고, 구성 요소를 재사용하며, 시나리오 테스트를 실행하고, 강력한 접근 제어 및 LLM 친화적인 출력으로 문서를 게시할 수 있는 통합 작업 공간을 제공합니다. AI 기반 엔드포인트 준수 검사, 엔드포인트 케이스, 게시 시 옵션(마크다운 페이지, llms.txt, MCP)과 같은 기능은 API가 일관되고 명확하며 통합하기 쉽게 유지하는 데 도움이 됩니다.
이미 OpenAPI 사양을 관리하고 있다면, 가장 중요한 흐름을 캡처하기 위해 Arazzo 설명을 함께 추가하는 것을 고려하십시오. 그런 다음 사양을 Apidog로 가져오고, 워크플로우 단계를 반영하는 테스트를 구축하며, 사람과 AI 비서 모두 성공하는 데 도움이 되는 문서를 게시하십시오. 이러한 조합은 재작업을 줄이고, 제공 속도를 높이며, API 설계에서 API 사양, 채택에 이르는 API 수명 주기 전반에 걸쳐 신뢰를 높입니다. 더 나아가 준비가 되셨습니까? Apidog에 가입하여 팀에 마찰 없이 훌륭한 API를 제공할 도구를 제공하십시오.