API 계약: API 명세를 아키텍처에 연결하기
몇 주 전, 아름다운 C4 다이어그램을 가진 팀과 시스템 아키텍처를 검토하고 있었습니다. 컨테이너는 잘 정의되어 있었습니다. 관계에는 명확한 레이블이 있었습니다. 모든 것이 훌륭해 보였습니다 — 누군가가 "주문 서비스와 결제 게이트웨이 사이의 API는 실제로 어떻게 생겼나요?"라고 물을 때까지.
침묵. 다이어그램에는 "REST/JSON"이라고 적혀 있었습니다. OpenAPI 명세는 다른 저장소에 있었습니다. 실제 엔드포인트 목록은 마지막 인턴이 떠난 이후 업데이트되지 않은 Notion 페이지에 있었습니다. 하나의 API 표면에 대한 세 가지 진실의 소스가 있었고, 어느 것도 일치하지 않았습니다.
이것은 터무니없이 흔합니다. API 명세는 코드베이스에서 가장 정밀하고 기계가 읽을 수 있는 산출물 중 하나입니다. 그러나 아키텍처 문서에서는 보이지 않습니다. 상자, 화살표, 프로토콜 레이블만 있습니다. 실제 계약 — 엔드포인트, 스키마, 필드 — 은 완전히 다른 곳에 있습니다.
이를 해결하기 위해 API 계약을 만들었습니다. API 명세가 이제 아키텍처 내에 존재하며, 이를 구현하고 소비하는 요소에 연결됩니다.
네 가지 프로토콜, 하나의 집
현대 시스템은 단일 프로토콜만 사용하는 경우가 드뭅니다. 공개 API는 REST이고, 내부 서비스는 gRPC로 통신하며, 프론트엔드는 GraphQL을 통해 데이터를 가져옵니다. 각각은 고유한 명세 형식, 고유한 도구, 고유한 문서 생태계를 가지고 있습니다.
Archyl의 API 계약은 네 가지 모두를 지원합니다:
OpenAPI / Swagger — OpenAPI 3.x 또는 Swagger 2.0 명세를 가져와 Scalar로 구동되는 대화형 참조 뷰어를 얻으세요. 엔드포인트는 그룹화되고, 매개변수는 문서화되며, 스키마는 확장 가능합니다. 전용 API 문서 도구에서 얻는 것과 동일한 경험이, 아키텍처 워크스페이스에 직접 내장됩니다.
gRPC / Protocol Buffers — .proto 정의를 붙여넣거나 동기화하세요. 뷰어는 서비스, 메서드, 메시지 타입, enum을 구문 강조와 적절한 들여쓰기로 렌더링합니다. 서비스가 무엇을 노출하는지 이해하기 위해 proto 파일을 뒤질 필요가 없습니다.
GraphQL — 스키마를 가져와 타입, 쿼리, 뮤테이션, 서브스크립션을 탐색하세요. 서버 엔드포인트를 구성했다면 완전한 GraphiQL 플레이그라운드를 얻습니다 — 쿼리를 작성하고 실제 API에 대해 실행하며, Archyl을 떠나지 않고 스키마를 대화형으로 탐색하세요.
AsyncAPI — AsyncAPI 명세로 이벤트 기반 API를 정의하세요. 뷰어는 채널, 작업, 메시지 스키마, 서버 바인딩을 완전한 구문 강조로 렌더링합니다. Kafka, RabbitMQ, NATS, WebSocket 중 무엇을 사용하든, AsyncAPI 계약은 서비스가 생성하고 소비하는 이벤트를 문서화합니다.
Git에서 가져오기 또는 직접 붙여넣기
API 명세는 변합니다. 엔드포인트가 추가되고, 필드가 폐기되고, 새 버전이 출시됩니다. 문서가 최신 상태를 유지하려면 수동 복사-붙여넣기가 필요하다면, 최신 상태를 유지하지 못할 것입니다.
그래서 API 계약은 두 가지 소스 모드를 지원합니다:
Git 동기화는 계약을 저장소의 명세 파일에 연결합니다. openapi.yaml, service.proto, schema.graphql, asyncapi.yaml을 지정하면 Archyl이 콘텐츠를 직접 가져옵니다. 상류에서 명세가 변경되면 동기화를 누르면 계약이 업데이트됩니다. Archyl이 지원하는 모든 Git 제공자 — GitHub, GitLab, Bitbucket, Azure DevOps, 자체 호스팅 인스턴스 — 에서 작동합니다.
수동은 명세를 Git에 보관하지 않는 팀이나 빠른 프로토타이핑을 위한 것입니다. 명세 콘텐츠를 직접 붙여넣고 제자리에서 편집하세요. 서비스가 존재하기 전에 계약을 초안 작성하거나, 제어하지 않는 서드파티 API의 명세를 가져오는 데 유용합니다.
두 모드 모두 버전 관리를 지원하므로 문서화하고 있는 계약의 버전을 추적할 수 있습니다.
아키텍처에 연결됨
여기서 API 계약이 단순한 명세 뷰어 이상이 됩니다.
모든 계약은 하나 이상의 C4 요소 — 시스템, 컨테이너, 컴포넌트, 코드 요소 — 에 연결할 수 있습니다. OpenAPI 명세는 이를 제공하는 API 게이트웨이 컨테이너에 연결할 수 있습니다. gRPC proto는 이를 구현하는 마이크로서비스 컴포넌트에 연결할 수 있습니다. GraphQL 스키마는 이를 노출하는 BFF(Backend for Frontend)에 연결할 수 있습니다.
이러한 링크는 양방향입니다. 계약에서 관련된 아키텍처 요소를 볼 수 있습니다. 다이어그램의 요소 상세 패널에서 API 표면을 설명하는 계약을 볼 수 있습니다. 캔버스에서 컨테이너를 마우스 오른쪽 버튼으로 클릭하면 컨텍스트 메뉴에서 직접 계약을 연결하거나 연결 해제할 수 있습니다.
이것은 처음에 설명한 격차를 메웁니다. 누군가가 "이 두 서비스 사이의 API는 어떻게 생겼나요?"라고 물으면, 답은 한 번의 클릭으로 얻을 수 있습니다. 다른 도구에 있지 않고, 다른 저장소에 있지 않고 — 바로 다이어그램에 있습니다.
이벤트 채널
이벤트 기반 아키텍처는 문서화하기 어렵기로 악명이 높습니다. 어떤 서비스가 어떤 토픽에 발행하는가? 메시지 스키마는 무엇인가? 누가 소비하는가?
Archyl의 이벤트 채널은 비동기 통신에 가시성을 제공합니다. 각 AsyncAPI 계약은 정의하는 채널 — 토픽, 큐, 스트림 — 을 자동으로 표면화하고 이벤트를 생산하고 소비하는 C4 요소에 매핑합니다.
다이어그램에서 이벤트 채널은 별개의 연결 유형으로 나타나, 어떤 관계가 동기식 API 호출이고 어떤 것이 비동기식 이벤트 흐름인지 즉시 명확해집니다. 이것은 시스템 동작을 이해하는 데 중요합니다: 두 서비스 간의 REST 호출은 메시지 브로커에 발행된 이벤트와는 매우 다른 신뢰성 및 결합 특성을 가집니다.
AsyncAPI 계약과 독립적으로 이벤트 채널을 만들 수도 있어, 공식 명세가 없는 레거시 메시징 시스템이나 독점 프로토콜을 문서화하는 데 유용합니다.
대화형 뷰어
계약이 원시 텍스트 덩어리가 되는 것을 원하지 않았습니다. 각 프로토콜은 목적에 맞게 구축된 뷰어를 제공합니다:
OpenAPI 뷰어는 완전한 대화형 API 참조를 렌더링합니다. 엔드포인트는 태그별로 구성되며, 확장 가능한 요청/응답 스키마, 매개변수 문서, 인증 세부사항이 있습니다. 서버 URL을 정의했다면 뷰어가 이를 표시하여 개발자가 요청을 어디로 보내야 하는지 알 수 있습니다. 구문 강조된 YAML 덤프가 아닌 실제 API 문서 경험입니다.
Protocol Buffer 뷰어는 적절한 구문 색상으로 proto 정의를 렌더링하여 서비스, RPC, 메시지 구조를 쉽게 스캔할 수 있게 합니다.
GraphQL 뷰어는 타입, 필드, 디렉티브를 강조합니다. 서버 엔드포인트를 구성하면 두 번째 탭에서 완전한 GraphiQL 플레이그라운드가 열립니다. 라이브 API에 대해 쿼리를 작성하고 실행하며, 인트로스펙션을 통해 스키마를 탐색하고, 뮤테이션을 테스트할 수 있습니다 — 모두 Archyl에 내장되어 있습니다. GraphQL API에 여러 환경(스테이징, 프로덕션)이 있으면 여러 서버 항목을 정의하고 전환할 수 있습니다.
AsyncAPI 뷰어는 채널 목록, 메시지 스키마, 서버/브로커 구성과 함께 이벤트 기반 API 정의를 렌더링합니다. 각 채널은 작업(발행/구독), 페이로드 스키마, 바인딩을 보여주어 개발자에게 이벤트 기반 통신 표면의 명확한 그림을 제공합니다.
시작하기
아무 프로젝트로 이동하여 사이드바에서 API 계약 섹션을 여세요. "계약 추가"를 클릭하고 프로토콜 유형과 소스 모드를 선택하세요.
Git 소스 계약의 경우, 저장소를 연결하고(또는 프로젝트에 이미 연결된 것을 재사용하고) 파일 경로와 브랜치를 지정하면 Archyl이 명세를 가져옵니다. 수동 계약의 경우 콘텐츠를 직접 붙여넣으세요.
생성 후, 다이어그램으로 이동하여 관련 C4 요소에 계약을 연결하세요. 그 시점부터 아키텍처를 탐색하는 누구나 다이어그램 자체에서 실제 API 표면을 드릴다운할 수 있습니다.
왜 이것이 중요한가
아키텍처 다이어그램은 구조를 보여주는 데 강력합니다 — 무엇이 존재하고 어떻게 연결되는지. 하지만 인터페이스에 대해서는 항상 약했습니다. "REST/HTTPS"로 레이블된 관계 화살표는 두 서비스 사이에 실제로 무엇이 흐르는지에 대해 거의 아무것도 알려주지 않습니다. Kafka 토픽에 발행된 이벤트는 더욱 불투명합니다 — AsyncAPI 명세와 채널 매핑이 바로 거기에 없다면 말이죠.
API 계약은 그 격차를 메웁니다. 화살표에 정밀성을 추가합니다. 새 팀원이 아키텍처를 보고 모바일 앱과 API 게이트웨이 사이의 연결을 발견하면, 즉시 OpenAPI 명세를 열어 정확히 어떤 엔드포인트가 사용 가능한지, 어떤 데이터 구조가 교환되는지, 어떤 인증이 필요한지 이해할 수 있습니다.
이것은 존재 가치를 입증하는 아키텍처 문서입니다. 누군가가 의무화해서가 아니라, 매일 발생하는 실제 질문에 답하기 때문입니다.
이미 아키텍처에 Archyl을 사용하고 계신가요? 프로젝트에서 API 계약 기능을 탐색하세요. 플랫폼이 처음이신가요? C4 모델에 대해 알아보고 AI 기반 탐색이 어떻게 아키텍처 다이어그램을 자동으로 생성할 수 있는지 읽어보세요.