API 설계는 조직 계약

---

이 글의 결론

API 설계는 “어떻게 호출할까”가 아니라 “어디까지 책임질 것인가”를 고정하는 조직 간 계약이다.

---

왜 API를 계약으로 봐야 하는가

API는 기능 명세가 아니라, 시스템 경계와 팀 간 책임 분리를 강제하는 도구다.

왜

대규모 시스템에서 실패는 내부 구현이 아니라 경계(boundary) 에서 발생한다.
API가 모호하면 변경 비용은 폭증하고, 팀 간 조율 비용이 기술 부채로 전이된다.

무엇

API 설계란 다음을 결정하는 행위다.

• 어떤 정보가 노출되는가
• 무엇이 변경 불가한가
• 누가 책임지는가

어떻게

RPC와 REST는 스타일의 문제가 아니라,

• 조직 구조
• 변경 빈도
• 장애 전파 방식
  에 따라 선택해야 할 계약 형태다.

---

API 설계의 목표 5가지

좋은 API는 내부를 숨기고, 변경 비용을 외부로 밀어내지 않는다.

1. 경계 명확화: 소유권과 책임 범위 고정
2. 변경 비용 제어: 내부 변경이 외부에 전파되지 않도록
3. 버전 전략 내재화: 진화 가능성 확보
4. 보안 기준 명시: 인증·인가·데이터 노출 수준
5. 관측성 확보: 호출 단위의 추적·에러 해석 가능

---

RPC vs REST 비교

이 둘의 차이는 문법이 아니라 ‘결합도’다.

구분	RPC	REST
핵심 개념	함수 호출	리소스 상태 전이
장점	명확한 동작, 낮은 오버헤드	느슨한 결합, 진화 용이
단점	강한 결합, 변경 비용 큼	설계 난이도 높음
조직 적합성	소규모/단일 팀	다팀/외부 공개
진화 전략	동시 배포 전제	점진적 확장
실패 전파	즉각적	완충 가능

---

언제 RPC를 쓰는가 / 쓰지 말아야 하는가

RPC는 ‘내부 최적화 계약’이다.

언제 쓰는가

• 단일 조직, 소수 팀
• 호출 의미가 명령 중심일 때
• 성능·지연 시간이 핵심 제약일 때

쓰지 말아야 하는가

• 외부 공개 API
• 빈번한 요구사항 변경
• 팀 간 배포 독립성이 필요할 때

---

언제 REST를 쓰는가 / 쓰지 말아야 하는가

REST는 ‘진화 가능한 경계 계약’이다.

언제 쓰는가

• 다수의 소비자(웹/모바일/외부)
• 도메인이 상태 중심일 때
• 장기적인 버전 공존이 필요할 때

쓰지 말아야 하는가

• 내부 단기 프로젝트
• 명령형 워크플로우가 핵심일 때
• 과도한 추상화가 오히려 비용일 때

---

예시 1: 포럼 서비스 API

읽기 중심 도메인은 REST가 유리하다.

좋은 API (REST)

GET /posts/{id}
200 OK
{
"id": 1,
"title": "...",
"author": {...}
}

나쁜 API

POST /getPost
{
"postId": 1
}

문제:

• 동작 중심 명명
• 캐시 불가
• 의미 확장 어려움

---

예시 2: 커머스 결제 내부 API

결제는 RPC가 현실적일 수 있다.

좋은 API (RPC)

ChargePayment(orderId, idempotencyKey)
→ Success | Failure

이유:

• 명령 의미 명확
• 트랜잭션 경계 분명
• 내부 동시 배포 가능

---

REST 설계에서 자주 망하는 포인트 7개

REST를 쓴다고 RESTful해지는 건 아니다.

1. 동사 기반 URI (/createUser)
2. HTTP 상태 코드 무시
3. 멱등성 고려 없음
4. 리소스와 행동 혼합
5. 과도한 엔드포인트 분화
6. 버전 전략 부재
7. 에러 스키마 불일치

---

API 계약 관점 핵심

API는 한 번 공개되면 되돌릴 수 없다.

Backward Compatibility

• 필드 추가는 OK
• 필드 제거/의미 변경은 계약 파기

버전 전략 3가지

1. URI 버전 (/v1)
   • 명확, 비용 큼
2. Header 버전
   • 유연, 복잡
3. 필드 기반 확장
   • 가장 이상적, 설계 난이도 높음

선택 기준: 소비자 수 × 변경 빈도

---

좋은 API / 나쁜 API 최소 스펙

좋은 API

• 명확한 리소스
• 예측 가능한 응답
• 에러 구조 통일

나쁜 API

• 호출마다 의미 다름
• 상태 코드 무시
• 문서 없이는 사용 불가

---

면접 질문 10개 & 답변 구조

API 질문은 설계 사고를 본다.

1. 왜 REST를 선택했는가?
2. RPC의 단점은?
3. 버전은 어떻게 관리하는가?
4. Breaking change 기준은?
5. 멱등성은 어떻게 보장하는가?
6. 에러는 어떻게 설계하는가?
7. 인증/인가 위치는?
8. 관측성은 어떻게 확보하는가?
9. 외부 공개 시 달라지는 점은?
10. 조직 구조와의 관계는?

모범 구조
맥락 → 제약 → 선택 → 포기한 것

---

재학습 체크리스트 (10)

• 이 API의 소비자는 누구인가
• 변경 빈도는 어느 정도인가
• 배포 독립성이 필요한가
• 명령인가 상태인가
• 버전 전략이 있는가
• 멱등성이 필요한가
• 에러가 계약화돼 있는가
• 인증 경계가 명확한가
• 관측 가능한가
• 조직 구조와 일치하는가

---

API 리뷰 체크리스트 (실무용 15)

1. 리소스 명확성
2. URI 일관성
3. 상태 코드 사용
4. 에러 스키마
5. 멱등성
6. 인증/인가
7. 버전 전략
8. 문서화 수준
9. 변경 영향도
10. 캐시 가능성
11. 확장 여지
12. 관측성
13. 테스트 용이성
14. 소비자 관점
15. 조직 경계 일치 여부

---

한 줄 요약

RPC와 REST의 선택은 기술 취향이 아니라, 조직과 변경 비용의 문제다.

---

• 참고: 소프트웨어 아키텍처 및 대규모 시스템 설계