프로덕션에서 당신을 괴롭히는 8가지 API 설계 실수

Source: Dev.to

API는 영구적입니다. 이는 14개의 클라이언트 팀에 걸쳐 파괴적인 변경을 조율하면서 아무도 유지하고 싶어 하지 않는 호환성 쉼을 통해 오래된 엔드포인트를 계속 살아 있게 해야 할 때까지는 극적으로 들릴 수 있습니다. 나쁜 코드는 조용히 리팩터링될 수 있습니다. 하지만 나쁜 API 계약은 매 분기마다 이자를 복리로 쌓아가는 공개 부채와 같습니다.

다음은 당시에는 합리적으로 보였지만, 프로덕션에 배포된 뒤 실제 고통을 초래한 여덟 가지 디자인 패턴입니다.

실수 1: 처음부터 버전 관리하지 않음

초기 버전 관리를 하지 말아야 한다는 주장은 합리적으로 들립니다 — 아직 무엇이 바뀔지 모르기 때문이죠. 문제는 단 하나의 외부 클라이언트가 프로덕션에 들어가는 순간 “나중”이 찾아온다는 것입니다. 그 시점에서 버전 관리를 추가하려면 단순히 결정만 하는 것이 아니라 마이그레이션이 필요합니다.

URL 경로 버전 관리(/v1/users, /v2/users)는 가장 명시적인 접근 방식이며 대부분의 팀에 기본으로 적합합니다. 인프라 수준에서 라우팅하기 쉽고 모든 로그 파일에 표시됩니다. Stripe가 이를 사용하는 이유는 명확성이 Stripe API가 업계에서 가장 잘 설계된 API 중 하나로 평가받는 중요한 이유이기 때문입니다.

실수 2: 일관되지 않은 명명 규칙

같은 API에서 camelCase와 snake_case를 혼용하는 것은 문서 부채입니다. 이는 소비자에게 시도와 오류를 통해 모호성을 해결하도록 강요합니다. 규칙 선택 자체보다 일관성이 더 중요합니다 — 하나를 선택하고 직렬화 레이어에서 강제하세요, 관습에 맡기고 기대하지 마세요.

실수 3: 기본적으로 너무 많은 데이터를 반환하기

리소스에 대해 알고 있는 모든 정보를 반환하는 엔드포인트는 관대해 보일 수 있습니다. 실제로는 성능에 큰 부담이 됩니다. /users/{id} 가 프로필, 선호도, 결제 내역, 활동 로그까지 모두 반환한다면, 모든 모바일 클라이언트는 즉시 버리는 데이터에 대한 직렬화 비용을 지불하게 됩니다.

관련된 함정이 N+1 문제입니다. 주문당 전체 고객 객체를 가져오는 /orders 엔드포인트는 주문 목록에 대해 하나의 쿼리를 실행하고, 각 주문마다 고객을 위한 추가 쿼리를 실행합니다. 페이지네이션은 옵션이 아니라 기본값이어야 하며, 시계열 데이터의 경우 오프셋 기반보다 커서 기반 페이지네이션이 더 신뢰할 수 있습니다.

Mistake 4: Poor Error Responses

A generic 500 with no body is an absence of information dressed as a response. Stripe’s error format is the standard worth emulating: HTTP status code, machine‑readable code field, human‑readable message, and enough context to reproduce the problem. Validation errors should identify which fields failed and why, not just “validation failed.”

Mistake 5: No Rate Limiting

레이트 제한이 없는 API는 의도치 않은 서비스 거부(denial‑of‑service)를 초래할 수 있는 초대장과 같습니다. 버그가 있는 재시도 루프를 가진 클라이언트가 모든 사용자를 위해 서비스 전체를 중단시킬 수 있습니다. 슬라이딩 윈도우 카운터 알고리즘은 기본값으로 적합합니다: 전체 슬라이딩 로그의 정확성을 고정 윈도우의 메모리 효율성과 결합합니다. 응답 헤더(X-RateLimit-Remaining, Retry-After)에 제한을 노출하여 정상적인 클라이언트가 이에 맞게 동작하도록 합니다.

실수 6: 멱등성 무시

네트워크 요청이 성공과 구분할 수 없을 정도로 실패할 수 있습니다. 타임아웃 — 서버가 응답하기 전에 처리를 완료했는지 여부는 어떻게 알 수 있을까요? 쓰기 작업의 경우, 무작위 재시도는 중복 청구나 일관성 없는 상태를 초래할 수 있습니다. Stripe는 재무 데이터를 수정하는 모든 POST 요청에 멱등성 키를 요구합니다. 외부 클라이언트를 확보하기 전에 구현하고, 중복 청구에 대한 첫 번째 지원 티켓 이후가 아니라 바로 적용하세요.

실수 7: 사후 생각으로서의 인증

API 키는 서버‑간 통신에 적합합니다. OAuth 2.0은 사용자를 대신하여 동작할 때 적합합니다. JWT는 인증 스키마가 아니라 토큰 형식이며, 이를 자동으로 안전하다고 간주하면 none 알고리즘 취약점에 빠지게 됩니다. 첫 번째 외부 소비자와 연결하기 전에 인증 방식을 결정하세요. 나중에 뒤늦게 적용하는 것은 고통스럽습니다.

Mistake 8: Coupling Internal Models to API Responses

데이터베이스 행을 직접 API 응답으로 직렬화하는 것은 다음 리팩터링을 할 때까지는 효율적입니다. 컬럼 이름을 바꾸면 깨지는 변경을 배포하게 됩니다. password_hash와 같은 내부 필드를 추가하면 우연히 노출될 위험이 있습니다. Data Transfer Objects — 각 응답의 형태를 정의하는 명시적인 직렬화 클래스 — 는 내부 구현과 외부 계약 사이에 의도적인 경계를 만듭니다.

세 가지 핵심 요점

• 지체할 수 없는 구조적 결정은 버전 관리, 오류 형식, 인증 모델, 그리고 내부 모델과 외부 계약 사이의 경계입니다. 이를 사후에 적용하는 비용이 많이 듭니다. 나머지는 반복적으로 개선할 수 있습니다.
• API 설계 실패는 외부에 전가됩니다. 설계가 좋지 않아 발생하는 고통은 여러분이 통제하지 못하는 일정에 따라 소비자가 부담합니다. 이러한 비대칭은 대부분의 내부 엔지니어링 결정보다 더 많은 사전 주의를 정당화합니다.
• Stripe, GitHub, Twilio를 연구하세요. 유명해서가 아니라 그들의 설계 선택이 의도적이고 문서화되어 있기 때문입니다. 일관성, 페이지네이션, 오류 처리, 버전 관리를 위해 사용하는 패턴은 충분한 이유가 있습니다.

전체 기사는 novvista.com에서 각 실수에 대한 자세한 분석, 실제 구현 예시, Stripe, GitHub, Twilio가 표준을 어떻게 설정했는지에 대한 분석을 확인하세요.

원본은 NovVista