10년 뒤에도 깨지지 않는 API 설계

HTTP·OpenAPI·OAuth·Webhook·SDK의 호환성과 운영 계약

장기 소비자를 위한 호환성과 운영 계약을 설계한다.

상태: 출간 후보 웹교정쇄 · 자동 QA 통과 · API·보안 감수 대기 · 22개 장

HTTP·OpenAPI·OAuth·Webhook·SDK의 호환성과 운영 계약

기준일: 2026-08-14 · 상태: 출간 후보 웹교정쇄 · 자동 QA 후 사람 현장 감수 대기

FieldPass Partner API를 소비자가 안전하게 업그레이드할 수 있는 장기 계약으로 만든다. 대상 독자는 REST endpoint는 만들지만 버전 변경·재시도·오류·SDK 운영이 어려운 백엔드 개발자다. 기능을 따라 입력하는 데서 끝내지 않고 결정의 전제, 실패, 증거와 rollback을 한 세트로 남긴다. 숫자·한도·가격·UI는 영구 사실이 아니며 실습 직전 공식 문서를 다시 확인한다.

FieldPass는 방문 예약, 기사 배정, 사진, 결제와 정산을 가진 합성 B2B 서비스다. 여섯 권이 같은 tenant-demo, res-demo-101, run-demo-001을 사용한다. 따라서 도메인 결정이 API, telemetry, infrastructure, event와 edge에서 같은 의미인지 비교할 수 있다.

npm run test로 여섯 위험 fixture를 실행한다.
npm run build로 원고와 SVG를 재생성한다.
lab/public/index.html을 열어 입력·판정·증거·원복을 같은 화면에 기록한다.
실제 cloud·domain 적용은 소유자 승인, 비용 상한과 별도 staging에서만 한다.


cd fieldpass-platform
npm run qa
npm start

먼저 version 9로 의도한 실패와 Problem Details를 확인하고 새 process에서 version 1로 성공·Outbox 대사를 실행한다. 실제 cloud·domain 변경은 소유자 승인과 비용 상한이 있는 staging에서만 한다.


{"type":"https://api.example.invalid/problems/version-conflict","title":"Version conflict","status":409,"instance":"urn:demo:incident:01"}


POST /v1/reservations HTTP/1.1
Idempotency-Key: demo-command-001
If-Match: "v3"


compareApiSchemas({required:['id','status']},{required:['id','status','memo']});


node --test test/platform-lab.test.mjs

contracts/openapi.yaml을 정본으로 열고 예약 확정 요청의 필수 header, expectedVersion과 Problem Details를 확인한다. npm run verify:openapi 뒤 실제 HTTP E2E를 실행해 spec과 runtime의 status·content-type·ETag가 같은지 대사한다. 문서 generator 성공은 계약 일치의 증거가 아니다.

새 memo 필드를 선택 필드로 추가한 schema와 필수 필드로 추가한 schema를 만든다. 기존 consumer fixture가 전자는 견디고 후자는 호환성 gate에서 실패해야 한다. enum 추가, 알 수 없는 field, null과 누락, cursor의 동일 시각 tie-break도 같은 방식으로 시험한다.

멱등성 실습은 같은 key·같은 body의 결과 재사용과 같은 key·다른 body의 409를 모두 검증한다. webhook은 raw body signature, timestamp, replay window, eventId inbox와 재전송 log가 필요하다. 제거할 endpoint에는 소비자 inventory, 대체 경로, 관측 기간과 rollback window를 붙인다.

1장. API는 함수가 아니라 조직 간 약속이다
2장. 스타일을 문제에 맞게 고른다
3장. Resource와 상태 전이를 모델링한다
4장. HTTP 의미를 지킨다
5장. 오류를 RFC 9457 계약으로 만든다
6장. 입력 schema는 닫힌 세계가 아니다
7장. Pagination은 데이터 변화까지 설계한다
8장. 동시성은 ETag와 version으로 드러낸다
9장. 멱등성은 키 저장소까지 포함한다
10장. 인증과 인가를 분리한다
11장. Rate limit은 공정성과 복구 계약이다
12장. 비동기 작업에 상태 resource를 준다
13장. Webhook은 서명·중복·순서가 핵심이다
14장. Schema evolution은 소비자 관점이다
15장. Version은 마지막 수단이다
16장. OpenAPI를 실행 계약으로 쓴다
17장. SDK는 제품이다
18장. Gateway와 API 책임을 나눈다
19장. 관측 가능성을 계약에 넣는다
20장. API 보안 test를 자동화한다
21장. Deprecation과 종료를 운영한다
22장. 최종 캡스톤과 출간 게이트

10년 뒤에도 깨지지 않는 API 설계

목차