API-first architecture
Concept
API 우선 아키텍처는 사용자 인터페이스보다 먼저 비즈니스 기능을 안정적이고 호출 가능한 API로 설계하여, 사용자 인터페이스, 워크플로 엔진, AI 에이전트가 동일한 작업을 사용하도록 합니다.
함께 다룬 주제
API-first architecture 관련 에피소드에서는 Computer-Using Agent (CUA), Foundry Agent Service, Service account, Agent observability, Microsoft Agent 365 및 Software as a service (SaaS)도 다룹니다.
Description
API 우선 아키텍처는 사용자 인터페이스를 구축하기 전에 비즈니스 기능을 안정적이고 호출 가능한 API로 정의하는 설계 방식입니다. 이후 동일한 작업을 사용자 인터페이스, 워크플로 엔진, AI 에이전트가 소비하며, 각 클라이언트가 별도의 경로로 로직에 접근하는 대신 하나의 API를 공유합니다. 이 모델에서 API는 코드의 부산물이 아니라 제품 수준의 결정으로 취급됩니다. 외부 개발자, 파트너, AI 에이전트가 이를 기반으로 개발할 것으로 예상되기 때문입니다.
API 우선 개발의 핵심 요소는 API 계약입니다. Microsoft의 API 우선 개발 관련 문서에 따르면, 계약은 엔드포인트, 요청 및 응답 데이터, 예상되는 오류를 설명하며, 구현이나 사용자 인터페이스보다 먼저 작성됩니다. 계약은 보통 기계가 읽을 수 있는 형식, 가장 흔하게는 OpenAPI로 표현됩니다. 계약이 승인되면 백엔드 팀은 이를 구현하고, 프런트엔드 및 모바일 팀은 계약에서 생성된 목(mock)을 기준으로 개발합니다. 문서, SDK, 테스트 역시 동일한 원본에서 생성할 수 있어 여러 산출물의 일관성을 유지할 수 있습니다.
이 방식은 흔히 코드 우선 개발과 대비됩니다. 코드 우선 방식에서는 기존 코드로부터 API가 만들어지며, 이 과정에서 내부 세부 사항이 공개 인터페이스에 노출될 수 있습니다. API 우선 방식은 순서를 뒤집습니다. 인터페이스를 의도적으로 설계하고, 그에 맞게 코드를 작성합니다. Microsoft 페이지는 또한 절충점을 언급합니다. 계약 우선 작업은 초기 검토 노력을 추가로 요구하며, 소비자가 적고 인터페이스가 빠르게 변할 것으로 예상되는 초기 내부 도구에는 코드 우선 접근이 합리적일 수 있습니다. 이 페이지는 벤더 문서이며 Azure 관련 내용을 포함합니다.
버전 관리는 이 방식의 중요한 부분입니다. 소비자가 계약에 의존하므로, 버전 관리는 소비자와의 합의로 취급됩니다. 버전 내의 추가적 변경은 안전한 것으로 간주되는 반면, 호환성을 깨는 변경에는 새 버전이 필요합니다. 이전 버전의 폐기는 Sunset 헤더로 알릴 수 있으며, 이를 통해 소비자에게 갑작스러운 중단 대신 명확한 이전 경로를 제공합니다.
또 다른 특징은 하나의 API가 단일 게이트웨이를 통해 웹, 모바일, 파트너, 에이전트 클라이언트에 모두 서비스할 수 있다는 점입니다. 이 경우 인증과 속도 제한이 모든 호출자에게 일관되게 적용되며, 비즈니스 로직이 채널별로 중복되지 않습니다. 이 때문에 이 개념은 소프트웨어 에이전트가 호출할 예측 가능하고 문서화된 작업을 필요로 하는 에이전트 중심 시스템과 관련이 있습니다.
M365.FM 에피소드 "Computer-Using Agents: How CUA Could Transform SaaS"는 API 우선 아키텍처를 에이전트 생태계와 연결합니다. 이 에피소드는 API 우선 아키텍처를 채택할 때 에이전트 생태계가 번성한다고 설명하는데, 이는 에이전트, 시스템, 워크플로를 명확하고 예측 가능하게 연결하기 때문이라고 합니다. 안정적인 API를 지능형 시스템의 근간으로 묘사하며, 개발자가 중단에 대한 걱정 없이 이를 기반으로 혁신할 수 있다고 말합니다. 또한 확장성을 이점으로 언급하여, 조직이 변화하는 요구 사항에 적응하는 데 도움이 된다고 설명합니다. 이러한 맥락에서 API 우선 설계는 에이전트가 생성, 자동화, 확장할 수 있는 워크플로에 대한 투자와 함께 자리합니다.
API 우선 아키텍처와 관련된 일반적인 결정에는 어떤 기능을 API로 노출할지, 어떤 계약 형식을 사용할지, 변경을 어떻게 버전 관리하고 폐기할지, 공유 인증과 속도 제한을 위해 게이트웨이를 어디에 둘지가 포함됩니다. 팀은 또한 계약 검토에 드는 초기 비용을 병렬 프런트엔드 및 백엔드 작업의 이점, 그리고 생성된 문서 및 테스트의 이점과 비교하여 저울질합니다.
Overview compiled with AI from M365.FM episodes and the facts on this page. You can improve it with the edit button below.
| Type | Concept |
|---|---|
| Kind | Architecture |
Frequently asked questions
Questions marked with AI were written with AI from the facts on this page.
API 우선 아키텍처는 무엇을 의미합니까? (AI)
사용자 인터페이스보다 먼저 비즈니스 기능을 안정적이고 호출 가능한 API로 설계하여, 사용자 인터페이스, 워크플로 엔진, AI 에이전트가 모두 동일한 작업을 사용하도록 하는 것을 의미합니다. API 계약을 먼저 정의하고 구현이 그 뒤를 따릅니다.
API 우선 방식은 코드 우선 방식과 어떻게 다릅니까? (AI)
코드 우선 개발에서 API는 기존 코드의 부산물이며 내부 세부 사항을 노출할 수 있습니다. API 우선 개발에서는 보통 OpenAPI로 작성되는 계약을 구현이나 사용자 인터페이스를 만들기 전에 설계하고 승인합니다.
API 우선 방식이 AI 에이전트와 관련이 있는 이유는 무엇입니까? (AI)
"Computer-Using Agents: How CUA Could Transform SaaS" 에피소드는 안정적인 API가 지능형 시스템의 근간이며, 에이전트, 시스템, 워크플로를 명확하고 예측 가능하게 연결해 준다고 설명합니다. 게이트웨이 뒤의 단일 API는 웹 및 모바일 클라이언트와 함께 에이전트 클라이언트에도 서비스할 수 있습니다.
Community wiki
Short info above, community knowledge below: add practical tips, examples or corrections. New contributions are reviewed first; trusted members publish directly.
Experts and companies for this topic
Nobody has listed this topic yet. Add it to your profile.
Maintained by Mirko Peters (Microsoft MVP) · Last updated: