2.3 API와 인터페이스 설계

개요와 동기

API(애플리케이션 프로그래밍 인터페이스)는 한 소프트웨어가 다른 소프트웨어에 능력을 제공하는 계약입니다. 팀, 시스템, 조직이 만나는 곳이며, 잘못되었을 때 가장 오래가고 비싼 것입니다. 내부 함수 시그니처는 자유롭게 리팩터링할 수 있습니다. 공개된 API는 다릅니다. 만난 적 없을지도 모르는 소비자에 대한 약속이며, 그것을 깨면 그들이 깨집니다. 조직이 모놀리스를 서비스로 쪼개고 파트너와 대중에게 능력을 열수록, API는 주된 제품 표면이자 주된 통합 위험이 됩니다.

큰 팀에서 API는 사람들이 독립적으로 일하게 해 주는 것입니다. 잘 설계된 인터페이스는 모든 소비자와 조율하지 않고도 내부를 바꾸게 해 주며, 이것이 서비스 경계의 존재 이유입니다. 잘못 설계된 인터페이스는 내부 세부를 새게 하고, 보조를 맞춘 배포를 강제하고, 서비스 집합을 분산 모놀리스로 바꿉니다. 서비스가 쪼개졌지만 너무 결합되어 함께 빌드하고 배포해야 하는 것입니다. API 설계는 팀이 얼마나 독립적으로 움직일 수 있는지를 직접 결정합니다.

기업과 정부 환경에서 API는 컴플라이언스, 보안, 수명의 의무도 집니다. 공공 부문 API는 개방형 표준을 따르고, 수년 동안 안정적으로 유지되고, 조율할 수 없는 외부 개발자를 섬기도록 요구될 수 있습니다. 기업 API는 계약상의 서비스 수준을 갖춘 파트너 통합을 뒷받침합니다. 이 모든 것이 버전 관리 규율, 하위 호환성, 거버넌스, 개발자 경험의 기준을 높입니다.

핵심 원칙

계약을 먼저 설계하십시오. 인터페이스는 구현의 부산물이 아니라 의도적인 제품 결정입니다.
자신의 편의가 아니라 소비자의 경험에 최적화하십시오.
하위 호환성을 약속으로 다루십시오. 호환되지 않는 변경에는 새 버전과 이전 경로가 필요합니다.
쉬운 일을 올바르게 만드십시오. 합리적인 기본값, 예측 가능한 오류, 일관된 관례.
실패를 염두에 두고 설계하십시오. 멱등성(반복된 요청이 단일 요청과 같은 효과를 냄), 재시도, 페이지네이션, 속도 제한은 사후 생각이 아니라 일급 관심사입니다.
유행이 아니라 상호작용에 맞춰 프로토콜 스타일을 고르십시오.
API를 소유자, 수명주기, 문서화를 갖춘 제품으로 다스리십시오.

권장 사항

API 우선, 계약 주도로 일한다

구현을 쓰기 전에 리소스, 연산, 스키마, 오류 의미론을 포함한 API 계약을 정의하고 검토하십시오. 계약이 문서, 클라이언트 및 서버 스텁, 모의 서버, 검증을 생성할 수 있도록 기계가 읽을 수 있는 명세를 사용하십시오. 그러면 소비자는 여러분이 만드는 동안 모의 서버에 대해 통합을 시작할 수 있고, 계약은 양쪽이 테스트하는 단일 진실의 원천이 됩니다.

상호작용 스타일을 의도적으로 고른다

개인 선호가 아니라 상호작용에 따라 REST(표현 상태 전송), GraphQL, gRPC, 이벤트 기반 메시징 중에서 고르십시오. 리소스 중심이고 광범위하게 상호운용되며 캐시 가능한 인터페이스에는 REST를 쓰십시오. 다양한 클라이언트가 풍부한 그래프에 대해 유연하고 집계된 조회를 필요로 할 때는 GraphQL을 쓰십시오. 내부 서비스 사이의 고성능의 강한 타입 호출에는 gRPC를 쓰십시오. 비동기적이고 결합이 느슨한 워크플로와 상태 변경의 전파에는 이벤트 기반 메시징을 쓰십시오. 많은 큰 시스템이 여러 스타일을 동시에 쓰며, 각각 맞는 곳에 둡니다.

규율 있게 버전 관리하고 폐기한다

명시적인 버전 관리 전략과 공개된 폐기 정책을 채택하십시오. 변경을 어떻게 분류하는지, 옛 버전을 얼마나 오래 지원하는지, 소비자에게 어떻게 알리는지입니다. 하위 호환 변경(선택적 필드나 새 엔드포인트 추가)과 호환되지 않는 변경(필드 제거나 이름 변경, 타입이나 의미론 변경) 사이에 분명한 선을 그으십시오. 기존 필드의 의미를 절대 바꿔 쓰지 마십시오. 소비자에게 이전할 겹치는 기간을 주고 일정을 훨씬 앞서 알리십시오.

오류 의미론을 일관되고 기계가 읽을 수 있게 만든다

구조화되고 예측 가능한 오류를 반환하십시오. 안정적인 기계 가독 코드, 사람이 읽을 수 있는 메시지, 민감한 내부를 새지 않으면서 행동할 만한 충분한 맥락입니다. 클라이언트가 오류를 일관되게 처리할 수 있도록 모든 엔드포인트에 걸쳐 같은 상태 의미론을 쓰십시오. 소비자가 마주칠 수 있는 모든 오류를 문서화하십시오.

멱등성, 페이지네이션, 속도 제한을 내장한다

멱등성 키를 지원하여 쓰기 연산을 재시도해도 안전하게 만드십시오. 그러면 타임아웃 뒤에 재시도하는 클라이언트가 이중 청구하거나 이중 생성하지 않습니다. 모든 목록 엔드포인트를 첫날부터 페이지네이션하고, 크거나 변하는 데이터셋에는 커서 기반 페이지네이션을 선호하십시오. 속도 제한을 적용하고 문서화하며, 클라이언트가 우아하게 물러설 수 있도록 현재 제한 상태를 반환하십시오.

API를 다스리고 개발자 경험에 투자한다

각 API를 소유자, 수명주기, 카탈로그 항목이 있는 제품으로 다루십시오. 인터페이스가 팀 전반에서 일관되게 유지되도록 설계 리뷰나 API 표준 위원회를 마련하십시오. 개발자 경험에 투자하십시오. 정확한 참조 문서, 퀵스타트, 예제, 샌드박스, 변경 로그입니다. 큰 생태계에서는 API를 찾을 수 있게 하는 포털이나 카탈로그가 필수입니다.

장단점

스타일	가장 적합한 용도	장점	단점
REST / HTTP	공개적이고 리소스 지향적인 API	어디에나 있음, 캐시 가능, 단순, 상호운용	과다/과소 가져오기. 많은 왕복. 명세하지 않으면 느슨한 계약
GraphQL	다양한 클라이언트를 위한 유연한 조회	클라이언트가 지정하는 쿼리. 단일 엔드포인트. 강한 스키마	캐싱과 속도 제한의 복잡성. 쿼리 비용 위험. 서버 복잡성
gRPC	내부 고성능 호출	빠름, 간결, 강한 타입, 스트리밍	브라우저 지원이 약함. 사람이 읽기 어려움. 무거운 도구
이벤트 기반	비동기, 결합이 느슨한 워크플로	느슨한 결합. 확장 가능. 복원력	추론하기 더 어려움. 결과적 일관성. 운영 복잡성

버전 관리 전략은 안정성과 유지보수를 맞바꿉니다. 많은 옛 버전을 지원하면 소비자를 보호하지만, 유지하고 테스트해야 할 코드가 늘어납니다. 하위 호환성은 자신의 자유를 소비자의 안정성과 맞바꾸며, 널리 쓰이는 API에는 대개 올바른 거래입니다. 큰 그림은 이렇습니다. 나쁜 API 결정의 비용은 인터페이스의 전체 수명에 걸쳐 모든 소비자가 치릅니다. 그러니 거의 어디보다 경계에 더 많은 설계 노력을 쓸 가치가 있습니다.

팀과 논의할 질문

변경이 하위 호환인지 호환되지 않는지 어떻게 분류하며, 조용한 깨짐이 출시되기 전에 어떤 자동 검사가 잡아냅니까? 이 장은 분명한 선을 긋습니다. 선택적 필드와 새 엔드포인트를 추가하는 것은 안전하지만, 필드를 제거하거나 이름을 바꾸거나, 타입을 바꾸거나, 필드의 의미를 바꿔 쓰는 것은 소비자를 깨뜨립니다. 큰 팀에서 변경을 하는 사람은 모든 소비자를 볼 수 없는 경우가 많아서, “작은” 손질이 말을 나눈 적 없는 파트너를 조용히 깨뜨릴 수 있습니다. 구체적 신호를 회의에 가져오십시오. 공개된 명세에 대해 CI에서 자동 계약 호환성 검사를 실행합니까, 아니면 누군가 규칙을 기억하는 데 의존합니까? 호환되지 않는 변경이 모든 파트너에 걸친 조율된 이전을 강제하고 벤더 및 정권 교체에 걸칠 수 있는 기업과 정부 환경에서는 비용이 소비자 수에 따라 커집니다. 분류 규칙을 정하고 호환성 관문을 연결해, 호환되지 않는 변경이 통합이 아닌 빌드를 실패시키게 하십시오.
멱등성 키, 페이지네이션, 속도 제한 중 어떤 신뢰성 기본 요소가 모든 새 엔드포인트에서 첫날부터 필수입니까? 이 장은 이것들이 일급 관심사라고 주장합니다. 살아 있는 청구 엔드포인트에 멱등성 키를 나중에 붙이거나 이미 출시된 목록에 페이지네이션을 더하는 것 자체가 호환되지 않는 변경이기 때문입니다. 큰 생태계는 이를 증폭합니다. 테스트에서 동작하던 엔드포인트가 실제 데이터 양에서 무너지고, 멱등하지 않은 쓰기는 한 번의 네트워크 흔들림을 중복 청구로 바꿉니다. 현재 어느 엔드포인트에 이것이 없고 재시도 폭풍이 무엇을 할지에 대한 증거를 가져오십시오. 새 엔드포인트의 기본값을 협상 불가로 만드십시오. 모든 목록에 커서 페이지네이션, 모든 쓰기에 멱등성 키, 현재 상태를 반환하는 문서화된 속도 제한입니다. 이는 미래의 강제 이전을 일회성 설계 습관으로 바꿉니다.
구현을 쓰기 전에 계약을 진정으로 설계하고 리뷰합니까, 아니면 인터페이스가 코드에서 새어 나옵니까? API 우선 권장은 문서, 스텁, 모의 서버를 생성하고 소비자가 여러분이 만드는 동안 모의 서버에 통합하게 해 주는, 기계가 읽을 수 있고 사전에 검토되는 명세를 요구합니다. 계약이 구현을 뒤따르면 인터페이스가 내부 데이터베이스 구조를 노출하고 구현이 바뀔 때마다 바뀌며, 이것이 이 장의 최고 안티패턴입니다. 살펴볼 신호는 소비자가 오늘 여러분의 모의 서버에 통합을 시작할 수 있는지, 아니면 동작하는 백엔드를 기다려야 하는지입니다. 인터페이스가 제품 표면이자 가장 잘못하기 비싼 것인 공개 및 파트너 API에서, 계약에 하루를 쓰면 몇 주의 지원 소동을 아낍니다. 구현이 시작되기 전에 계약 리뷰를 필수 단계로 만드십시오.
두 팀이 같은 능력을 노출해야 할 때 어떤 상호작용 스타일이 이기며, 네 번째 프로토콜에 안 된다고 말할 권한은 누구에게 있습니까? 이 장은 REST, GraphQL, gRPC, 이벤트 기반 메시징을 상호작용 적합성으로 고르라고 하지만, 규모에서 진짜 위험은 모든 팀이 자기가 좋아하는 것을 골라서 소비자가 엔드포인트마다 다른 관례를 마주하는 것입니다. 큰 조직은 그 파편화의 대가를 클라이언트 라이브러리, 게이트웨이, 모니터링, 이제 하나가 아닌 네 가지 관용구를 배우는 모든 통합자의 인지 부하로 치릅니다. 이미 프로덕션에 있는 프로토콜의 목록, 각각이 섬기려고 선택된 상호작용, 하나 이상에 걸쳐 있는 소비자를 가져오십시오. 상충하는 고려는 진짜입니다. 공유된 기본값은 난립을 줄이지만, 경직된 의무는 gRPC 모양의 문제를 REST 모양의 구멍에 밀어 넣습니다. 예외 절차를 소유하는 표준 기구나 아키텍처 리뷰에 이름을 붙이십시오. 기업과 정부의 환경에서 스타일의 난립은 통합에 대한 영구적 세금이 되고, 파트너가 각각에 의존하게 된 뒤에는 되돌리기 어렵기 때문입니다.
공개된 폐기 정책은 무엇이며, 광고하는 지원 기간을 실제로 지킨다는 것을 증명할 수 있습니까? 이 장은 버전 관리와 폐기를 규율로 다룹니다. 옛 버전이 얼마나 오래 사는지, 소비자에게 어떻게 알리는지, 이전할 어떤 겹침을 얻는지에 대한 서면 정책입니다. 시행할 수 없는 약속은 없는 것보다 나쁩니다. 큰 생태계에는 말을 나누지 않는 소비자가 있어서, 폐기된 버전이 프로덕션에서 깨질 때까지 계속 호출하기 때문입니다. 증거를 논의에 가져오십시오. 오늘 몇 개의 살아 있는 버전을 유지하는지, 각각의 실제 사용량, 폐기된 엔드포인트를 여전히 호출하는 소비자를 볼 수 있는지, 마지막 종료가 얼마나 앞서 공지되었는지입니다. 상충하는 압력은 유지보수 비용 대 소비자 안정성이며 둘 다 실제입니다. 계약상의 서비스 수준을 가진 기업 파트너와 정권 및 벤더 교체를 넘어 살아남아야 하는 공공 부문 API에서, 지원 기간은 그것을 만든 팀보다 오래 지속될 수 있는 약속이므로, 누가 그것을 소유하는지와 종료가 일어나기 전에 안전함을 어떻게 증명할지 정하십시오.
개발자 경험이 좋은지 어떻게 알 수 있으며, API가 우리에게 동작한다고 해서 그렇다고 가정하고 있지는 않습니까? 이 장은 각 API를 채택이 정확한 참조 문서, 퀵스타트, 예제, 샌드박스, 변경 로그, 찾을 수 있는 카탈로그에 달린 제품으로 봅니다. 팀은 “API가 동작한다”를 “API를 쓸 수 있다”로 일상적으로 착각하며, 그 간극은 지원 티켓, 실패한 통합, 조용히 포기하는 소비자로 나타납니다. 의견이 아닌 측정 가능한 신호를 가져오십시오. 신규 통합자의 첫 성공 호출까지의 시간, 엔드포인트별 지원 티켓 양, 공개된 문서가 살아 있는 계약에 비해 얼마나 낡았는지, 신입이 팀에 이메일하지 않고 포털에서 스스로 해결할 수 있는지입니다. 긴장은 문서화와 포털이 기능 출시와 경쟁하는 실제 노력이 든다는 점이지만, 큰 생태계에서 나쁜 개발자 경험은 통합 비용을 수백 명의 소비자에게 한꺼번에 떠넘깁니다. 조율할 수 없는 외부 개발자를 섬기고 투명성이 의무화되는 경우가 많은 정부에서, 사용할 수 있고 잘 문서화되고 찾을 수 있는 인터페이스는 있으면 좋은 것이 아니라 공적 책임성 의무의 일부입니다.

분야별 관점

스타트업. 엔지니어가 두세 명이고 의식에 쓸 시간이 없으니, 계약은 가볍지만 실제로 유지하십시오. 만드는 동안 첫 디자인 파트너 고객이 통합할 수 있는 기계가 읽을 수 있는 단일 명세입니다. 아직 API 게이트웨이, 카탈로그, 거버넌스 위원회는 세우지 마십시오. 하지만 나중에 추가하기 고통스러운 두 습관, 쓰기의 멱등성 키와 목록의 커서 페이지네이션은 못 박아 두십시오. 살아 있는 엔드포인트에 소급 적용하는 것은 감당할 수 없는 호환되지 않는 변경이기 때문입니다. 하나의 상호작용 스타일, 거의 항상 REST를 선호하여 첫 해에 프로토콜 난립을 끌고 가지 마십시오.

소기업. 전담 API 전문가도 빠듯한 예산도 있으니, 명세에서 문서, 모의 서버, 클라이언트 스텁을 생성하는 도구에 의지하여 제너럴리스트가 깊은 프로토콜 전문성 없이 인터페이스를 유지할 수 있게 하십시오. 구매 대 개발을 신중히 저울질하십시오. 기성 게이트웨이나 API 관리 플랫폼은 직접 만들어야 했을 속도 제한, 키, 개발자 포털을 줍니다. 표면을 작게, 관례를 일관되게 유지하십시오. 추가되는 모든 엔드포인트와 일회성 오류 형식은 얇은 팀이 영원히 지원해야 하는 것이기 때문입니다.

대기업. 많은 자율 팀에 걸쳐 핵심 문제는 병목이 되지 않으면서 일관성을 유지하는 것입니다. 공유 스타일 가이드, API 표준 리뷰, 인터페이스를 찾을 수 있게 하는 카탈로그, 조용한 깨짐이 통합이 아닌 빌드를 실패시키도록 CI의 자동 하위 호환성 검사입니다. 각 API를 이름 있는 소유자, 수명주기, 공개된 폐기 정책이 있는 제품으로 다스리고, 포트폴리오가 건강하게 유지되도록 채택, 지원 부하, 호환되지 않는 변경 빈도를 측정하십시오. 상호작용 스타일과 버전 관리 규칙을 조직 전체에서 표준화하십시오. 이 규모에서 파편화는 비싼 기본값입니다.

정부. 조달 규칙, 개방형 표준 의무, 공적 책임성이 모든 선택을 형성합니다. 계약을 공개하고, 의무화된 개방형 표준을 따르고, 조율할 수 없는 외부 개발자가 스스로 해결할 수 있도록 샌드박스와 참조 문서를 제공하십시오. 통합이 정권과 벤더 교체를 넘어 살아남아야 하므로 장기 하위 호환성을 정책 요건으로 다루고, 호환되지 않는 변경을 드물고, 철저히 다스려지며, 훨씬 앞서 공지되게 하십시오. API와 문서를 대중과 감사의 정밀 검토를 견딜 만큼 투명하게 유지하고, 미래 정권을 가둘 독점 형식을 피하십시오.

사례

스타트업. 첫 공개 API를 출시하는 시드 단계 스타트업은 코딩 전에 계약을 기계가 읽을 수 있는 명세로 써서, 두 디자인 파트너 고객이 백엔드가 아직 만들어지는 동안 모의 서버에 통합할 수 있게 합니다. 소비자가 몇 명뿐이어도 청구 엔드포인트에 멱등성 키를, 모든 목록에 커서 페이지네이션을 더합니다. 파트너가 API에 의존하게 된 뒤에 소급 적용하면 감당할 수 없는 호환되지 않는 변경이 되기 때문입니다. 선행 계약은 하루가 들고 몇 주의 지원 왕복을 아낍니다.

대기업. 대형 결제 회사가 수천 개 가맹점에 공개 REST API를 노출합니다. 모든 쓰기 엔드포인트는 멱등성 키를 받으므로 네트워크 재시도가 중복 청구를 만들지 않습니다. 모든 목록 엔드포인트는 커서 페이지네이션을 씁니다. 오류에는 공개 참조에 문서화된 안정적인 코드가 담겨 있습니다. 공식 폐기 정책은 어떤 버전이든 사전 공지와 이전 가이드와 함께 긴 지원 기간을 보장합니다. 이 규율은 경쟁 우위입니다. 통합자는 API가 자신들 아래서 깨지지 않으리라 신뢰합니다.

정부. 한 국가 디지털 서비스가 시민 데이터를 위한 개방형 API를 의무화된 개방형 표준과 API 우선 설계 프로세스를 따라 공개합니다. 계약은 빌드 전에 명세되고 검토되며, 중앙 정부 API 카탈로그에 공개되고, 샌드박스와 함께 제공되어, 개별적으로 조율할 수 없는 서드파티 개발자가 스스로 통합할 수 있습니다. 통합이 정권과 벤더 교체를 넘어 살아남아야 하므로 장기 하위 호환성은 정책 요건입니다. 그래서 호환되지 않는 변경은 드물고 철저히 다스려집니다.

비즈니스 사례: 동기, ROI, TCO

좋은 API 설계는 시스템을 연결하고 파트너를 온보딩할 때 가장 큰 비용인 경우가 많은 통합 비용을 낮춥니다. 분명하고, 안정적이고, 잘 문서화된 API로는 소비자가 지원 티켓 한 건 없이 며칠 만에 통합합니다. 나쁜 API는 끝없는 지원 부하, 실패한 통합, 평판 훼손을 낳습니다. API 자체가 제품일 때 개발자 경험은 채택과 수익을 직접 좌우합니다.

가장 큰 숨은 비용은 호환되지 않는 변경입니다. 모든 호환되지 않는 변경은 내부 팀과 외부 파트너를 가리지 않고 모든 소비자에 걸친 조율된 이전을 강제하며, 총 비용은 소비자 수와 그들이 보조를 맞춰 움직이기가 얼마나 어려운지에 따라 커집니다. 계약 우선 설계, 하위 호환성, 버전 관리 규율에 선행 투자하면 이런 비싸고 조직 전체에 걸친 이전 사건을 피합니다. 리더십과 이야기할 때는 API 품질을 팀 자율, 파트너 생태계 성장, 값비싼 강제 이전 회피를 위한 지렛대 지점으로 설명하십시오. 통합 시간, 지원 티켓 양, 호환되지 않는 변경 빈도를 증거로 추적하십시오.

안티패턴과 함정

구현 우선 API: 인터페이스가 내부 데이터베이스 구조를 새게 하고 구현이 바뀔 때마다 바뀝니다.
조용한 호환되지 않는 변경: 버전 증가 없이 필드를 바꿔 쓰거나 검증을 조이면 소비자를 예측할 수 없게 깨뜨립니다.
수다스러운 인터페이스: 한 논리적 연산에 많은 왕복을 요구해 성능과 사용성을 해치는 설계.
일관되지 않은 관례: 모든 엔드포인트가 자기 명명, 오류 형식, 페이지네이션을 발명해 클라이언트가 일반화할 수 없는 것.
페이지네이션이나 속도 제한 없음: 테스트에서는 동작하다가 실제 데이터 양이나 부하에서 무너지는 엔드포인트.
멱등하지 않은 쓰기: 재시도가 중복을 낳고, 단 한 번의 네트워크 흔들림이 데이터를 망칩니다.
버전의 증식: 폐기 없이 너무 많은 살아 있는 버전이 있어 감당할 수 없을 때까지 유지보수를 늘립니다.
사후 생각으로서의 문서: 문서화되지 않았거나 낡은 참조가 모든 통합 비용을 소비자에게 떠넘깁니다.

성숙도 모델

1단계, 시작: API가 구현에서 부산물로 나타납니다. 공유 관례가 없고, 인터페이스가 내부 데이터베이스 구조를 새며, 호환되지 않는 변경이 흔하고 공지되지 않으며 소비자의 통합이 실패할 때 발견됩니다.
2단계, 발전: 일부 팀이 기본 REST 관례를 따르고, 비공식으로 버전 관리하고, 문서를 손으로 쓰지만, 관행은 팀마다 일관되지 않습니다. 멱등성, 페이지네이션, 속도 제한이 일부 엔드포인트에는 있고 일부에는 없으며, 소비자는 여전히 각 API의 특이점을 경우별로 배웁니다.
3단계, 표준화: 기계가 읽을 수 있는 명세를 갖춘 계약 우선 설계가 문서화되어 조직 전체에서 시행됩니다. 공개된 폐기 정책, 일관된 오류 의미론, 필수 멱등성, 커서 페이지네이션, 속도 제한이 모든 새 엔드포인트에 적용되며, 공유 스타일 가이드와 API 표준 리뷰가 팀 전반에서 인터페이스를 일관되게 유지합니다.
4단계, 관리: API 포트폴리오가 기준선에 대해 측정되고 통제됩니다. 자동 하위 호환성 검사가 CI에서 모든 변경을 관문으로 통제하고, 첫 성공 호출까지의 시간, 엔드포인트별 지원 티켓 양, 호환되지 않는 변경 빈도, 살아 있는 버전 수, 엔드포인트별 사용량을 추적하여 폐기와 설계 결정이 의견이 아닌 증거에 근거합니다. 각 API는 이름 있는 소유자가 있는 카탈로그의 다스려지는 제품이며, 서비스가 목표에서 벗어나면 지표가 행동을 촉발합니다.
5단계, 오케스트레이션: API 전략이 지속적으로 개선되고 조직 전체에 통합됩니다. 카탈로그, 게이트웨이, 버전 관리 규칙, 호환성 관문이 하나의 시스템으로 작동하고, 조직은 측정된 채택과 비용에 따라 인터페이스를 일상적으로 폐기하고, 통합하고, 범위를 다시 정하며, 상호작용 스타일과 버전 관리 표준은 생태계, 파트너, 기술이 변함에 따라 적응하고, 호환되지 않는 변경은 드물고 잘 관리됩니다.

논의를 위한 아이디어

내부 API가 외부에 공개할 만큼 안정적인 때를 어떻게 결정합니까?
여러분의 맥락에서 폐기된 버전의 알맞은 지원 기간은 얼마이며, 누가 비용을 댑니까?
내부적으로 GraphQL이나 gRPC가 REST를 대체해야 하는 곳은 어디이며, 가치보다 복잡성을 더할 곳은 어디입니까?
병목이 되지 않으면서 많은 자율 팀에 걸쳐 API 일관성을 어떻게 시행합니까?
AI가 소비할 수 있는 API와 에이전트 도구 인터페이스가 설계 관례를 어떻게 바꿔야 합니까?
호환되지 않는 변경이 출시되기 전에 어떤 자동 검사가 잡아낼 수 있습니까?

핵심 요점

계약을 먼저 설계하십시오. API는 제품이자 오래 가는 약속입니다.
하위 호환성은 소비자를 보호합니다. 호환되지 않는 변경에는 새 버전과 이전 경로가 필요합니다.
유행이 아니라 상호작용 적합성으로 REST, GraphQL, gRPC, 이벤트를 고르십시오.
멱등성, 페이지네이션, 속도 제한, 일관된 오류를 첫날부터 내장하십시오.
API를 소유자, 카탈로그, 강한 개발자 경험을 갖춘 제품으로 다스리십시오.

참고 문헌과 더 읽을거리

Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures (dissertation)
Arnaud Lauret, The Design of Web APIs
Mike Amundsen, RESTful Web APIs and Design and Build Great Web APIs
Sam Newman, Building Microservices
OpenAPI Specification; JSON Schema (as reference standards)
Martin Kleppmann, Designing Data-Intensive Applications