Previous
Next
백엔드 REST API 설계 심화 — 메서드·멱등성·HATEOAS·협상·버전·프로덕션

백엔드 REST API 설계 심화 — 메서드·멱등성·HATEOAS·협상·버전·프로덕션

· 42분 읽기 · 수정 고급 가이드
백엔드 REST API 설계 심화 — 메서드·멱등성·HATEOAS·협상·버전·프로덕션

이 글의 핵심

REST API를 “URL 나열”이 아니라 프로토콜 계약으로 다루기 위한 내부 원리입니다. 메서드 의미·멱등성, 하이퍼미디어, 협상, 버전, 운영 패턴을 한 번에 정리합니다.

들어가며

솔직히 말하면 REST는 완벽하지 않아요. 학교·세미나에선 “자원·표현·전이”가 예쁘게 정리돼 있지만, 실서비스에선 캐시, 재시도, 모바일 앱, 결제, 레거시 클라이언트가 동시에 얽혀서 “교과서 REST”랑은 거리가 있거든요. 저도 처음엔 엔드포인트만 예쁘게 짓면 된다고 생각했는데, 나중에 가면 메서드 의미, 멱등성, 협상, 버전에서 한 번씩 터지더라고요.

REST(Representational State Transfer)는 HTTP 위에서 자원·표현·전이를 일관되게 다루는 설계 규율이라는 점은 그대로고요. 이 글에서는 교과서 점수보다 “운영팀·클라이언트·장애 대응이 이해할 수 있는 계약” 쪽에 초점을 둘게요.

HTTP 메서드 의미론과 멱등성

HTTP 메서드는 그냥 “동사 모음”이 아니라 의미론(semantics) 이 있어요. 캐시, 프록시, 재시도가 전부 이걸 믿고 움직이기 때문에, 엉뚱하게 매핑하면 캐시가 오염되거나, 재전송 뒤에 “같은 효과”가 아니라는 걸 뒤늦게 깨닫는 경우가 생깁니다.

안전성(Safe)과 멱등성(Idempotent)

  • 안전(Safe): 이 메서드로 자원 상태를 안 바꾼다는 기대. GET, HEAD, OPTIONS가 대표적이에요(표준 의미를 따를 때).
  • 멱등(Idempotent): 같은 요청을 여러 번 보내도, 한 번 성공한 뒤의 자원 상태와 같다는 기대. 네트워크 재시도랑 직결되죠.

표 말고, 제가 실무에서 감 잡는 방식만 쭉 정리해볼게요.

  • GET — 안전, 멱등. 조회. 본문에 조건 넣는 것도 가능하긴 한데, 캐시·프록시랑 싸우지 않게만 설계하세요.
  • HEAD — 안전, 멱등. 메타만, 본문 없음. 헬스·존재 확인에 잘 씀.
  • OPTIONS — 보통은 안전·멱등 쪽이에요. CORS preflight나 “서버가 뭘 허용하는지” 노출일 때가 많고, 정책이 따로 필요해요. (* 다만 운영에선 로깅·과금 훅이 붙을 수 있어서 “완전 무해”는 아닐 수 있어요.)
  • PUT — 안전하진 않지만 멱등에 가깝다고 보면 돼요. 치환(replace) 느낌이 강하고, 없으면 만드는 식이면 팀끼리 문서에 못 박아요.
  • DELETE — 안전하진 않고 멱등으로 두는 경우가 많아요. 이미 지운 뒤 또 지우기 → 404냐 204냐는 팀마다 갈리니, 문서에 써 두는 걸 추천해요.
  • POST — 멱등 아님, 안전도 아님. 생성·액션·트리거 뭐든 부작용. 멱등 키 없이 두면 “재시도 = 중복” 지옥이 열릴 수 있어요. 저도 여기서 한 번 당해봤죠.
  • PATCH — 기본은 멱등이라고 보지 않는 편. JSON Patch/Merge Patch냐, 도메인 DTO냐에 따라 갈려요.

PUT과 PATCH의 실무적 구분

  • PUT: 리소스를 통째로 갈아끼운다는 모델이 잘 맞아요. 누락 필드를 null로 볼지, 기본값으로 둘지는 스키마+문서에 박아두세요.
  • PATCH: 부분 수정이 목적. JSON Merge Patch, JSON Patch, 팀 전용 JSON 등. Merge Patch는 null이 “삭제”로 가는 식의 함정이 있어서, 공개 API면 예시·오류 케이스를 문서에 넣는 걸 추천해요.

POST의 멱등성: 멱등 키(Idempotency-Key)

결제·주문처럼 딱 한 번만 성공해야 하는 POST엔, 클라이언트가 만든 Idempotency-Key랑, 서버 쪽 요청 지문 + TTL 두는 패턴이 흔해요. 같은 키·같은 본문이면 첫 성공 응답을 다시 돌려주고, 본문이 다르면 409로 티를 내는 식이죠.

POST /v1/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
Idempotency-Key: 7b291f6c-2c4a-4f1e-9d0a-3e8c5f2a1b00

{"amount":{"value":"1000","currency":"KRW"},"orderId":"ord_42"}

서버가 키 기준으로 결과를 캐시해두면, 재시도해도 같은 HTTP 상태·본문이 나가서 끊기는 망을 조금 흡수할 수 있어요.

GET에 쓰기를 넣지 않는 이유

GET은 캐시·프리패치·로그 쪽에서 “읽기”로 취급돼요. GET /cancelOrder?id=... 같은 설계는 제가 볼 때마다 불안해요. 중간 캐시, 크롤러, 브라우저 프리패치 때문에 의도치 않게 취소가 실행될 수 있거든요. 취소·환불은 POST나 DELETE로 모델링하고, CSRF·권한·감사 로그를 명시적으로 태우는 쪽이 마음이 편해요.

HATEOAS 구현 패턴

HATEOAS는 “응답 안의 링크가 다음 상태 전이를 말해 준다”는 아이디어예요. URL을 앱에 하드코딩한 리스트로 들고 있지 말고, 지금 응답에 붙은 rel을 따라가자는 쪽이죠.

왜 어렵고, 언제 가치가 있는가

  • 장점: URI가 바뀌거나, 권한·상태에 따라 다음 행동이 갈릴 때 서버가 통제할 수 있어요. 공개 API나 호환을 오래 끌고 가야 할 때 체감이 납니다.
  • 비용: 링크를 제대로 “실행”하려면 미디어 타입 합의랑 rel 사전이 필요해요. 모바일 앱만 붙는 내부 API면 OpenAPI + 버전으로 끝내는 팀도 많고요(저도 그 쪽이 더 많았어요).

HAL(application/hal+json)

_links에 self, next, 커스텀 관계를 둡니다.

{
  "id": "ord_42",
  "status": "PENDING_PAYMENT",
  "_links": {
    "self": { "href": "/orders/ord_42" },
    "pay": { "href": "/orders/ord_42/payments" },
    "cancel": { "href": "/orders/ord_42/cancellation" }
  }
}

클라이언트는 pay, cancel 같은 rel만 알면 되고, href가 조금 바뀌어도 덜 아파요.

JSON:API 스타일

links·relationships로 연관을 표현하는 방식. 규격이 묵직한 대신 일관성이 좋고, 팀이 프레임워크를 같이 쓰면 설계 비용을 상쇄할 때가 있어요.

Siren, Collection+JSON

actions에 메서드·필드 스키마를 실어 “폼 같은” 하이퍼미디어를 표현. 브라우저가 아닌 API에서 “지금 뭘 할 수 있는지”를 기계가 읽게 하고 싶을 때 쓰면 좋아요.

“가벼운 하이퍼미디어” 타협

전부 도입이 부담이면, 최소한 이런 식은 어떨까요.

  1. 관계 이름 → URL 맵을 응답에 넣기 (_actions 팀 표준 등).
  2. 오류에 type URI(문제 문서)랑 hints(재시도 가능 여부).
  3. OpenAPI에 링크/확장 필드까지 같이 박기.

100% HATEOAS는 아니어도, “링크로 조금씩 진화”하는 느낌은 가져갈 수 있어요.

콘텐츠 협상(Content Negotiation)

같은 URI인데 표현만 다를 때, Accept, Accept-Language, Accept-Encoding, Content-Type으로 합의하는 과정이에요.

프로액티브 협상(요청 헤더 기반)

클라이언트가 선호를 보내죠.

GET /reports/2026/q1 HTTP/1.1
Host: api.example.com
Accept: application/vnd.example.report+json; version=1, application/json;q=0.8
Accept-Language: ko-KR, en;q=0.7

서버는 가능한 표현을 골라 주거나, 없으면 406을 줄 수도 있어요. 현장에선 406 대신 기본 포맷 + 경고 헤더를 쓰는 팀도 있는데, 계약을 빡세게 가져가려면 406이 더 솔직할 때도 있죠.

리액티브 협상(300/링크)

300이나 Link로 대안 URL을 주는 식. CDN·캐시 키랑 잘 엮이는지 먼저 본 다음 쓰는 걸 추천해요.

Content-Type과 415 Unsupported Media Type

POST/PATCH 본문이 기대한 형식이 아니면 415를 주면 클라이언트 입장에선 디버깅이 쉬워요.

언어 협상과 데이터 로캘

Accept-Language는 UI 문구엔 잘 맞는데, 금액·날짜·규정 텍스트는 도메인 규칙이 먼저인 경우가 많아요. locale 쿼리나 preferredLocale이랑 우선순위를 문서에 적어두면 싸움이 줄어요.

압축과 전송 협상

Accept-Encoding: gzip, br은 대역폭에 꽤 영향이 있고, ETag/Last-Modified랑 If-None-Match로 304 잘 쓰면 조회 비용이 확 줄기도 해요.

API 버전 관리 전략 — 제가 겪은 이야기

버전은 “URL에 v1 쓰자”로 끝나는 주제가 아니에요. 호환 변경 vs 파괴적 변경이 뭔지, 언제 끊을지까지 포함한 계약이거든요.

스토리: /api만 있던 시절

예전 팀에선 처음엔 그냥 /api/orders만 썼어요. 괜찮다고 생각했죠. 그런데 모바일 앱 옛날 빌드가 아직 떠 있고, B2B 파트너는 한 달에 한 번만 배포하고, 웹은 매주 나가고… 요구가 갈리면서 필드 의미가 살짝씩 바뀌기 시작했어요. “옵셔널로 넣은 필드”가 나중엔 “사실상 필수”가 되고, null 의미가 바뀌고, 그때부터는 “이건 v2다”라고 외치지 않으면 누가 뭘 쓰는지 모호해졌죠.

그때 회의에서 나왔던 말이 대략 이랬어요.

  • URL에 /v1 넣자 쪽: 게이트웨이·로그·온콜이 “아 v1이구나” 하고 필터하기 좋다. 캐시 키도 직관적.
  • Accept로 버전 나누자 쪽: URI는 그대로 두고 싶다. 대신 Vary: Accept랑 프록시 설정을 손봐야 하고, 디버깅은 약간 난이도 업.
  • 쿼리 ?apiVersion=2: 구현은 쉬운데, 로그·WAF 룰에 섞여 들어가서 대규모에선 잘 안 쓰는 팀이 많아요(저희는 후보에서 빨리 뺐어요).

정답은 없고, 지금의 게이트웨이·CDN·클라이언트 믹스에 맞는 쪽을 고르는 수밖에 없어요. 중요한 건 “우리 팀에선 이게 파괴적이다”를 문서에 못 박는 거예요.

URL 경로 (/v1/resource)

눈에 잘 보이고 라우팅/모니터링에서 쪼개기 쉬워요. public id 같은 도메인 식별자는 버전에 끌려다니지 않게 안정적으로 유지하는 편이 마음이 편해요.

헤더·Accept 기반

URI는 가만히 두고 싶을 때. 캐시에 Vary: Accept 잊지 말기.

쿼리 파라미터

단순하지만 프록시·로그랑 잘 섞여서 대규모에선 덜 쓰는 편이에요.

호환 / 파괴 / 폐기

  • 호환에 가깝다: 선택 필드 추가, enum에 값 추가(모르는 값은 무시), 오류만 세분화… 버전을 안 올리고 갈 수 있을 때가 많고요.
  • 파괴적: 필드 삭제, 의미 뒤집기, 갑자기 필수 필드. 이때는 새 버전이나 새 미디어 타입/프로파일을 열심히 논의하게 돼요.
  • 폐기: Deprecation, Sunset, Link의 sunset으로 “언제까지, 뭘로 갈아타라”를 알려 주고, 로그에서 옛 호출 비율 보면서 단계적으로 끊어요. 제가 해본 팀에선 “일정 + 대체 URL”이 없는 폐기 공지는 거의 민원이었어요.

프로덕션 REST API 패턴

관측 가능성(Observability)

  • 상관 ID: X-Request-Id나 traceparent로 로그·메트릭·트레이스를 한 요청으로 이어지게.
  • 구조화 로그: method, route_template, status, latency_ms 정도는 일정하게.
  • SLO: p95/p99, 에러율을 버전·라우트별로 보기.

오류 모델

RFC 7807 Problem Details(application/problem+json)로 type, title, status, detail 맞춰 두면 클라이언트가 기계적으로 분기하기 쉬워요. 스택은 밖으로 안 뺍니다.

인증·인가

공개망이면 OAuth 2.1 범위 안에서 Bearer, 파트너는 mTLS, 키 회전은 JWKS… 팀 룰에 쓰는 게 좋고요. 권한은 OpenAPI에 메모하거나 정책 저장소랑 엮는 식.

레이트 리밋·쿼터

429 + Retry-After + RateLimit-* 류. 비용 폭탄 막는 데 거의 필수예요.

캐시와 조건부 GET

ETag/Last-Modified 쓰는 조회 API는 트래픽 크면 체감이 커요. 개인정보 쪽은 Cache-Control: private로.

API 게이트웨이와 BFF

게이트웨이는 인증·레이트·WAF·라우팅, BFF는 클라이언트별로 응답 합성. 내부 REST랑 바깥에 보이는 계약을 나누면 진화 속도 맞추기 쉬워요.

호환성 테스트

Pact 같은 소비자 주도 계약, OpenAPI 스냅샷, 스테이징 리플레이… 브레이킹은 CI에서 먼저 잡죠.

보안 기본기

TLS, HSTS(브라우저), CSRF(쿠키 세션), 입력 검증, 대량 할당, 업로드 크기, SSRF… REST만의 이야기라기보다 공통이에요.

정리

  • 메서드는 안전·멱등이라는 “공개된 약속”에 먼저 맞추고, POST 비멱등은 멱등 키로 수습하는 경우가 많아요.
  • HATEOAS는 HAL·JSON:API·Siren으로 갈 수도 있고, 부담이면 가벼운 링크 + Problem Details + OpenAPI로 점진적으로 가도 괜찮아요.
  • 협상은 Accept/Content-Type/언어/압축이 한 세트이고, 캐시·Vary·조건부 GET이랑 같이 머리 써야 해요.
  • 버전은 URL이든 헤든, 누가 언제까지 뭘 쓰는지를 조직이 같이 봐야 하고, 저도 여기서 회의를 제일 많이 했어요.
  • 운영에선 관측·오류 표준·레이트·캐시·게이트웨이·계약 테스트가 REST랑 떼어놓고 말하기 어렵습니다.

REST는 완벽하지 않아요. 그래서 이론 점수보다, 지금 팀에 맞는 계약·버전·장애 대응이 맞는지를 자주 점검하는 편이 낫다고 봅니다.

심화 부록: 구현·운영 관점

이 부록은 앞선 본문을 런타임·운영 쪽에서 다시 압축한 거예요. 입력 검증 → 핵심 연산 → 부작용 → 관측으로 잘라 보면 장애 추적이 빨라집니다.

내부 동작과 핵심 메커니즘

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]
sequenceDiagram
  participant C as 클라이언트/호출자
  participant B as 경계(런타임·게이트웨이·프로세스)
  participant D as 의존성(API·DB·큐·파일)
  C->>B: 요청/이벤트
  B->>D: 조회·쓰기·RPC
  D-->>B: 지연·부분 실패·재시도 가능
  B-->>C: 응답 또는 오류(코드·상관 ID)
  • 불변 조건을 문장으로 적어두면 장애 났을 때 “어디가 깨졌는지” 빨라요.
  • 순수한 층과 시간·I/O 층을 나누면 테스트가 살아납니다.
  • 백프레셔: 큐/스트림에서 병목을 어디에 둘지도 미리 이야기해 두면 좋고요.

프로덕션 운영 — 표 말고 질문만

  • 관측성 — 상관 ID 있나요. 에러율·p95/p99, 의존성 타임아웃/재시도가 대시보드에 보이나요.
  • 안전성 — 검증·권한·시크릿·감사가 경로마다 일관되나요.
  • 신뢰성 — 재시도는 멱등 연산에만 걸리나요. 서킷·백오프·DLQ가 있나요.
  • 성능 — N+1, 풀 크기, 인덱스, 캐시, 백프레셔를 데이터 양에 맞게 쓰고 있나요.
  • 배포 — 롤백 루북, 카나리, 마이그레이션, 피처 플래그가 문서화돼 있나요.
  • 용량 — 피크 때 FD·스레드·디스크 상한을 가끔 흔들어 보나요.

스테이징은 데이터 양·RTT·동시성을 프로덕션에 가깝게 갈수록 재현이 잘 돼요.

확장 예시: 엔드투엔드 체감

  1. 입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드를 경계에 둔다.
  2. 핵심 경로 계측: 요청 ID, 단계별 지연, 외부 호출 결과 코드를 로그·메트릭·트레이스에서 한 흐름으로 본다.
  3. 실패 주입: 의존성 타임아웃·5xx·부분 데이터·락 대기를 스테이징에서 재현한다.
  4. 호환·롤백: 설정/마이그레이션/클라이언트 버전을 되돌릴 수 있는지 확인한다.
  5. 부하 후 검증: 피크 대비 p95/p99, 에러율, 리소스 상한, 알림 임계값을 점검한다.
handle(request):
  ctx = newCorrelationId()
  validated = validateSchema(request)
  authorize(validated, ctx)
  result = domainCore(validated)
  persistOrEmit(result, idempotentKey)
  recordMetrics(ctx, latency, outcome)
  return result

문제 해결(Troubleshooting)

  • 간헐적 실패 — 레이스, 타임아웃, DNS, 외부 의심. 최소 재현 → 트레이스로 가설 확인.
  • 성능 저하 — N+1, 동기 I/O, 락, 직렬화, 캐시 미스. APM/프로파일러로 핫스팟 하나씩.
  • 메모리 증가 — 캐시 무한 성장, 리스너 누수, 큰 버퍼, 커넥션 미반납. TTL·상한·스냅샷 비교.
  • 빌드/배포만 실패 — env, 권한, 플랫폼, lockfile. CI vs 로컬 diff.
  • 설정 불일치 — 프로필, 시크릿, 리전. 검증된 설정 단일 소스가 있으면 편해요.
  • 데이터 불일치 — 비멱등 재시도, 아웃박스, 캐시 무효화. 트랜잭션 경계 다시 보기.

순서는 보통: (1) 최소 재현 (2) 최근 변경 좁히기 (3) 환경 차이 (4) 관측 (5) 고치고 회귀·부하.

배포 전엔 git add → git commit → git push 하고 npm run deploy 가는 흐름이면 실수가 줄어요.

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

A. HTTP 메서드·멱등성, HATEOAS(가벼운 링크 포함), Accept 협상, 버전 이야기, 멱등 키, 게이트웨이까지 한 번에 훑는 용도예요. 팀 상황에 맞게 골라 쓰면 됩니다.

Q. 선행으로 읽으면 좋은 글은?

A. 하단 관련 글이나 C++ 시리즈 목차를 따라가도 좋고, HTTP 기본은 따로 익혀 두면 이 글이 더 잘 읽혀요.

Q. 더 깊이 공부하려면?

A. RFC·공식 문서, cppreference는 주제에 따라 쓰면 됩니다. 이 글은 REST 쪽이 메인이에요.

같이 보면 좋은 글 (내부 링크)

이 주제와 연결되는 다른 글입니다.

이 글에서 다루는 키워드 (관련 검색어)

REST, API설계, HTTP, HATEOAS, 멱등성, 콘텐츠협상, API버전, 백엔드 등으로 검색하시면 이 글이 도움이 됩니다.