API 설계자가 URL 경로 버전 관리와 내부-외부 모델 분리를 프로덕션 이전에 구현하지 않으면 외부 클라이언트 의존성 증가 시 breaking change 마이그레이션의 기술 부채가 누적되는 상황

Context

내부 코드는 조용히 리팩토링할 수 있지만 API 계약은 클라이언트 팀 14개에 동시 배포해야 하는 공개적 의사소통 수단이다. 외부 클라이언트가 프로덕션에 도달하는 순간이 '나중'이到来的 시점이며, 이후 버전 관리를 추가하려면 마이그레이션이 필요하다. 잘못된 설계 결정은 분기마다 이자가 붙는 부채로 전환된다.

Technical Solution

• [버전 관리] → URL 경로 버전(/v1/, /v2/)을 첫 번째 외부 클라이언트 이전에 적용하여 인프라 레벨 라우팅과 로그 가시성 확보
• [명명 규칙] → camelCase와 snake_case 중 하나를 선택하고 시리얼라이제이션 레이어에서 강제 적용
• [데이터 반환] → 페이지네이션을 기본값으로 설정하고 타임시리즈 데이터에는 cursor-based 페이지네이션 적용
• [에러 처리] → HTTP 상태 코드, machine-readable code, human-readable message, 재현 가능한 컨텍스트를 포함한 Stripe 형식의 구조화된 에러 응답 설계
• [Rate Limit] → Sliding Window Counter 알고리즘으로 메모리 효율과 정확도 균형 유지, X-RateLimit-Remaining과 Retry-After 헤더로 클라이언트 적응 허용
• [멱등성] → 금융 데이터 변경 POST 요청에 idempotency key 필수 적용, 네트워크 타임아웃 시 중복 처리 방지
• [인증] → 서버 간 통신은 API Key, 사용자 위임은 OAuth 2.0, JWT는 토큰 형식으로만 사용
• [모델 분리] → DB Row 직접 직렬화 대신 DTO(명시적 Serializer Class) 도입으로 내부 구현과 외부 계약 간 의도적 경계 생성