리처드슨 3단계가 곧 “진짜 REST”인가요?

성숙도는 참고 모델입니다. 실무에서는 2단계(올바른 HTTP)와 계약 문서(OpenAPI)·버전 정책을 갖추는 경우가 많고, 3단계 HATEOAS는 공개·장기 진화 API에서 가치가 큽니다.

PATCH는 항상 비멱등인가요?

RFC 5789는 PATCH의 멱등성을 보장하지 않습니다. 다만 특정 미디어 타입과 서버 구현에 따라 멱등하게 만들 수 있으며, 그 경우에도 클라이언트는 기본적으로 비멱등으로 가정하는 편이 안전합니다.

버전은 URL(/v1)이 표준인가요?

단일 표준은 없습니다. 경로 버전은 가시성과 프록시·모니터링에 유리하고, Accept 기반은 URI 안정성에 유리합니다. 게이트웨이·CDN·캐시 키 설계와 맞춰 선택합니다.

HATEOAS 없이 REST라고 불러도 되나요?

엄밀한 논의에서는 하이퍼미디어 구동을 강조하지만, 업계에서는 HTTP 기반 리소스 API를 넓게 REST로 부릅니다. 대신 계약·버전·오류 모델을 명확히 하는 것이 실무에서 중요합니다.

[2026] REST API 완전 가이드 — HTTP 의미론·리처드슨 성숙도·HATEOAS·버전·프로덕션

2026년 4월 7일 · 52분 읽기 · 수정 2026년 4월 7일 고급 가이드

이 글의 핵심

REST를 URL 나열이 아니라 HTTP 위의 계약으로 이해하기 위한 가이드입니다. 메서드 의미·리처드슨 성숙도·하이퍼미디어·협상·버전·운영 패턴을 한 흐름으로 다룹니다.

들어가며

REST(Representational State Transfer)는 범용 인터페이스(HTTP) 위에서 자원·표현·상태 전이를 일관되게 다루는 설계 규율입니다. 엔드포인트 이름만 다듬는 수준을 넘어서려면 메서드 의미, 안전성·멱등성, 성숙도 모델, 하이퍼미디어, 표현 협상, 진화 가능한 계약(버전), 프로덕션 운영이 함께 맞물려야 합니다. 이 글은 실무에서 자주 막히는 프로토콜·아키텍처 내부 관점을 정리합니다.

리처드슨 성숙도 모델

리처드슨 성숙도(Richardson Maturity Model)는 REST 스타일 API가 HTTP 기능을 얼마나 “의도에 맞게” 쓰는지를 네 단계로 나눈 참고 프레임입니다. “점수”가 아니라 팀이 어디에 서 있는지 진단하고 다음 개선을 논의하는 언어로 쓰는 것이 좋습니다.

Level 0: HTTP를 터널로만 쓰는 단계

하나의 엔드포인트(예: 단일 POST)에 모든 연산을 실어 보내는 원격 프로시저 호출(RPC)에 가까운 형태입니다. HTTP는 전송 수단일 뿐이고, 메서드·상태 코드·캐시 의미론을 거의 활용하지 않습니다. 레거시 연동이나 급한 마이그레이션에서 보일 수 있으나, 캐시·프록시·표준 클라이언트 동작과의 합치가 떨어집니다.

Level 1: 자원(리소스) 중심

여러 URI로 “대상”을 나눕니다. 예를 들어 /orders, /orders/{id}, /customers/{id}처럼 식별 가능한 자원이 드러납니다. 다만 아직 HTTP 메서드 의미가 일관되지 않거나, 모든 변경이 POST로 처리되는 식의 혼합이 남을 수 있습니다.

Level 2: HTTP 메서드와 상태 코드 활용

GET/POST/PUT/PATCH/DELETE를 의도에 맞게 매핑하고, 200/201/204/400/404/409/429 등 의미 있는 상태 코드로 결과를 표현합니다. 이 단계부터 중간 캐시, 조건부 요청(ETag 등), 재시도·멱등성 같은 HTTP 생태계의 이점을 제대로 가져갈 수 있습니다. 많은 공개 API가 목표로 삼는 실무적 “RESTful”의 핵심에 해당합니다.

Level 3: 하이퍼미디어 컨트롤(HATEOAS)

응답에 다음에 할 수 있는 행동(링크·폼·관계 이름) 이 포함되어, 클라이언트가 URL을 하드코딩하지 않고 표현이 제공하는 전이를 따릅니다. 서버가 워크플로를 바꿔도 연결 관계(rel) 수준에서 흡수할 여지가 생깁니다. 대신 미디어 타입·관계 사전·클라이언트 해석 비용이 들어가므로, 모바일 단일 앱처럼 배포 주기가 짧은 경우에는 OpenAPI+버전으로 대체하는 팀도 많습니다.

성숙도를 어떻게 적용할까

내부 마이크로서비스: Level 2 + 명확한 오류 모델·멱등 설계가 보통 균형이 좋습니다.
공개·파트너 API: Level 2를 넘어 Deprecation 헤더·Problem Details·버전 정책이 우선이며, 필요 시 HAL/JSON:API 등으로 Level 3 요소를 부분 도입합니다.
“진짜 REST” 논쟁보다 소비자(클라이언트)·운영·보안이 이해하는 계약을 갖추는 쪽이 생산적입니다.

HTTP 메서드 의미론과 멱등성

HTTP 메서드는 임의의 “동사”가 아니라 RFC 9110 등에서 규정한 의미론(semantics) 을 가집니다. 클라이언트·캐시·프록시·재시도 로직이 이를 전제로 동작하므로, 잘못 매핑하면 캐시 오염, 중복 부작용, 복구 불가한 상태로 이어질 수 있습니다.

안전성(Safe), 멱등성(Idempotent), 캐시 가능성

안전(Safe): 요청이 자원 상태를 바꾸지 않는다는 기대. GET, HEAD, OPTIONS(표준 의미를 따를 때)가 대표적입니다.
멱등(Idempotent): 동일 요청을 여러 번 보내도 자원 상태가 한 번 성공한 결과와 같다는 기대. 재전송·재시도와 직결됩니다.
캐시 가능(Cacheable): 응답이 캐시될 수 있는지는 메서드와 Cache-Control 등에 따릅니다. GET은 조건부로 캐시되기 쉽지만, 개인 데이터는 private/no-store로 명시해야 합니다.

실무에서 자주 참고하는 정리는 다음과 같습니다.

메서드	안전	멱등	비고
GET	예	예	조회. URI에 민감 정보를 넣는 것은 로그·Referer 유출에 유의
HEAD	예	예	메타데이터만; 본문 없음
OPTIONS	예*	예	CORS preflight 등. 노출 범위는 보안 정책으로 제한
PUT	아니오	예	치환(replace) 모델이 자연스러움. 없으면 생성 가능(계약에 따름)
DELETE	아니오	예	이미 삭제된 자원에 대한 재요청 시 404 vs 204 등은 팀 합의로 통일
POST	아니오	아니오	생성·액션·파이프라인 트리거. 멱등 키 없으면 중복 생성 위험
PATCH	아니오	보통 아니오	부분 수정. 표현 형식에 따라 멱등성 여부가 달라짐

* OPTIONS는 “부작용 없음”이 일반적이나, 로깅·과금 훅은 운영 정책으로 정의합니다.

PUT과 PATCH의 실무적 구분

PUT: 리소스 전체 표현을 치환한다는 모델이 자연스럽습니다. 누락 필드를 null로 볼지, 기본값으로 둘지는 스키마·문서에 명시해야 합니다.
PATCH: 부분 갱신이 목적입니다. application/merge-patch+json, application/json-patch+json, 도메인 특화 JSON 등 표현이 갈립니다. Merge Patch는 null이 삭제 의미가 되는 등 함정이 있으므로 공개 API에서는 예시와 오류 케이스를 문서화하는 것이 좋습니다.

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

결제·주문·티켓처럼 한 번만 성공해야 하는 POST에는 클라이언트 생성 멱등 키(예: Idempotency-Key 헤더)와 서버 측 요청 지문 저장소(TTL)를 두는 패턴이 널리 쓰입니다. 동일 키·동일 본문이면 최초 성공 응답을 재생하고, 본문이 다르면 409 Conflict 등으로 충돌을 드러냅니다.

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"}

GET에 쓰기를 넣지 않는 이유

GET은 캐시·프리패치·프록시·크롤러에 의해 의도치 않게 반복 실행될 수 있습니다. GET /cancelOrder?id=... 같은 설계는 실무에서 위험합니다. 상태 변경은 POST/PUT/PATCH/DELETE로 모델링하고, 권한·CSRF(브라우저)·감사 로그를 명시적으로 태웁니다.

CONNECT·TRACE 등

CONNECT는 일반적으로 프록시 터널 용도로 쓰이며, 공개 REST API 설계의 중심은 아닙니다. TRACE는 진단용이며 보안상 비활성화하는 환경이 많습니다. 일반적인 REST 자원 API 설계에서는 GET/HEAD/OPTIONS와 엔티티를 바꾸는 메서드에 집중하면 됩니다.

HATEOAS 원리와 구현 패턴

HATEOAS(Hypermedia as the Engine of Application State)는 응답에 실린 링크가 애플리케이션 상태 전이를 이끈다는 REST의 제약을 말합니다. 클라이언트는 고정된 URL 목록보다 rel로 식별되는 전이를 따라 업무를 진행합니다.

자원 상태 vs 애플리케이션 상태

자원 상태: 서버가 저장한 도메인 데이터(주문 상태, 잔액 등).
애플리케이션 상태: “지금 이 클라이언트가 어디까지 진행했는가”에 해당하는 세션성. HATEOAS는 후자를 하이퍼미디어 링크로 인코딩하려는 시도입니다.

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

장점: URI 변경·권한에 따른 가용 액션 숨김·워크플로 분기를 서버가 통제. 공개 API·장기 호환에 유리할 수 있음.
비용: 클라이언트가 링크를 실행 가능한 명령으로 해석하려면 미디어 타입 합의와 관계 이름 사전이 필요합니다.

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" }
  }
}

클라이언트는 rel 이름만 알면 되고, href 변경에 더 강해집니다.

JSON:API·Siren·Collection+JSON

JSON:API: links·relationships·included로 연관을 표현. 규격이 무겁지만 일관성이 좋습니다.
Siren: 엔티티에 actions(메서드·필드 스키마)를 실어 폼형 하이퍼미디어를 표현합니다.
Collection+JSON: 컬렉션 중심 하이퍼미디어. 특정 도메인에 맞을 때 채택합니다.

“가벼운 하이퍼미디어” 절충

전 규격 도입이 부담이면:

응답에 관계 이름 → URL 맵(_actions 등 팀 표준)을 둡니다.
RFC 7807 Problem Details로 type URI와 힌트를 제공합니다.
OpenAPI로 링크 필드·Link 헤더를 문서화합니다.

콘텐츠 협상(Content Negotiation)

콘텐츠 협상은 동일 자원(URI)에 대해 표현(representation)을 선택하는 과정입니다. 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 Not Acceptable을 반환할 수 있습니다. 엄격한 계약을 원하면 406이 분명하고, 관대한 모드에서는 기본 표현+경고 헤더를 쓰기도 합니다.

리액티브 협상(300·Link)

300 Multiple Choices나 Link 헤더로 대안을 제시합니다. CDN·캐시 키와 맞물리므로 캐시 전략을 먼저 정합니다.

`Content-Type`과 `415 Unsupported Media Type`

POST/PATCH 본문 형식은 Content-Type으로 식별합니다. 지원하지 않는 조합이면 415가 클라이언트에게 명확합니다.

압축과 조건부 GET

Accept-Encoding: gzip, br과 ETag/Last-Modified를 함께 쓰면 If-None-Match로 304를 유도해 비용을 줄일 수 있습니다.

API 버전 관리 전략

버전은 문자열 하나가 아니라 호환 변경과 파괴적 변경의 정의, 릴리스·폐기 정책, 소비자 통지를 포함한 계약입니다.

URL 경로 (`/v1/...`)

장점: 가시성, 라우팅·게이트웨이·모니터링에서 분리 용이.
주의: 도메인 식별자(public id) 는 버전과 독립적으로 안정적으로 유지하는 편이 좋습니다.

헤더·Accept 기반

Accept: application/vnd.example.v2+json처럼 미디어 타입에 버전을 심습니다.

장점: URI 안정.
주의: 캐시 키에 Vary: Accept가 필요하고 디버깅 난이도가 올라갈 수 있습니다.

쿼리 파라미터 (`?apiVersion=2`)

단순하지만 로그·프록시 규칙과 섞이기 쉬워 대규모 공개 API에서는 덜 선호되는 편입니다.

호환성 규칙 예시

호환(비파괴) 변경: 선택 필드 추가, enum 값 추가(클라이언트가 알 수 없는 값은 무시), 오류 코드 세분화.
파괴적 변경: 필드 제거·의미 변경·필수 필드 추가 → 새 버전 또는 새 미디어 타입/프로파일.

폐기(Deprecation)

Deprecation, Sunset, Link의 sunset(RFC 8594) 등으로 일정과 대체 경로를 알립니다. 로그에서 구버전 호출 비율을 보고 단계적 차단합니다.

프로덕션 REST 패턴

관측 가능성(Observability)

X-Request-Id 또는 W3C traceparent로 로그·메트릭·트레이스를 연결합니다. method, route_template, status, latency_ms, tenant 등 구조화 필드를 일관되게 남깁니다.

오류 모델

RFC 7807 Problem Details(application/problem+json)로 type, title, status, detail, instance를 맞추면 클라이언트가 기계적으로 분기하기 쉽습니다. 스택 트레이스는 노출하지 않습니다.

인증·인가·테넌시

공개 인터넷에서는 OAuth 2.x 범위에서 Bearer, 파트너 연동은 mTLS, 키 회전은 JWKS 등을 문서화합니다. 권한은 리소스 단위 RBAC/ABAC을 OpenAPI나 정책 엔진과 연결합니다.

레이트 리밋·쿼터

429 Too Many Requests와 Retry-After, RateLimit-*(관행)으로 백오프 가능성을 제공합니다.

캐시·프라이버시

조회 API는 ETag/Last-Modified로 조건부 요청을 지원하면 비용이 줄어듭니다. 개인 데이터는 Cache-Control: private 또는 no-store로 명시합니다.

게이트웨이·BFF·타임아웃

게이트웨이: 인증, 레이트 리밋, WAF, 라우팅, 카나리.
BFF: 클라이언트별 응답 합성. 도메인 서비스의 REST와 외부 계약을 분리합니다.
데드라인: 업스트림 호출에 개별 타임아웃·재시도 상한을 두고, 전체 요청에 예산(deadline) 을 전파하면 장애 전파를 줄입니다.

멱등성 저장소·중복 제거

POST 멱등 키 외에도 소비자 재처리(at-least-once) 환경에서는 자연 키 기반 upsert, Outbox, 메시지 중복 키 등과 조합해 정확히 한 번에 가깝게 만드는 설계가 필요합니다.

계약 테스트와 호환성

Pact 등 소비자 주도 계약으로 브레이킹 변경을 CI에서 걸러냅니다. OpenAPI 스키마 스냅샷과 스테이징 트래픽 리플레이로 회귀를 줄입니다.

페이징·부분 실패

오프셋은 단순하지만 대량 데이터에서 비용이 커질 수 있어 커서(키셋) 기반을 고려합니다. 배치 작업은 202 Accepted + 상태 폴링 URL로 비동기화합니다.

보안 기본기

TLS 강제, 입력 검증, 대량 할당 방지, 업로드 크기 제한, SSRF 방어, 로그의 PII 마스킹은 REST를 넘어 공통 과제입니다.

정리

리처드슨 성숙도는 진단용 모델이며, 실무에서는 보통 Level 2(올바른 HTTP) + 계약·버전을 바탕으로 필요 시 하이퍼미디어를 부분 도입합니다.
HTTP 메서드는 안전성·멱등성이라는 공개 의미에 맞춰야 하며, POST 비멱등성은 멱등 키로 보완하는 것이 정석에 가깝습니다.
HATEOAS는 HAL·JSON:API·Siren 등으로 구체화할 수 있고, 전부가 부담이면 관계 링크 + Problem Details + OpenAPI로 점진적으로 옮길 수 있습니다.
콘텐츠 협상은 Accept/Content-Type/압축/언어의 합의이며, Vary와 조건부 요청을 함께 설계해야 합니다.
버전은 URL·헤더·미디어 타입 등 여러 방식이 있으며, 핵심은 파괴적 변경의 정의와 폐기 정책을 조직이 공유하는 것입니다.
프로덕션에서는 관측성·오류 표준·레이트 리밋·캐시·게이트웨이·데드라인·계약 테스트가 REST 설계와 분리되지 않습니다.

REST를 규격 자체에 맞추는 것보다, 클라이언트·운영·보안이 동일한 가정을 갖는 계약으로 완성한다는 관점에서 점검해 보시길 권합니다.

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

이 부록은 앞선 본문에서 다룬 주제(「[2026] REST API 완전 가이드 — HTTP 의미론·리처드슨 성숙도·HATEOAS·버전·프로덕션」)를 구현·런타임·운영 관점에서 다시 압축합니다. 도메인별 세부 구현은 글마다 다르지만, 입력 검증 → 핵심 연산 → 부작용(I/O·네트워크·동시성) → 관측의 흐름으로 장애를 나누면 원인 추적이 빨라집니다.

내부 동작과 핵심 메커니즘

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)

불변 조건(Invariant): 버퍼 경계, 프로토콜 상태, 트랜잭션 격리, FD 상한 등 단계별로 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
결정성: 순수 층과 시간·네트워크·스케줄에 의존하는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
경계 비용: 직렬화, 인코딩, syscall 횟수, 락 경합, 할당·GC, 캐시 미스를 의심 목록에 둡니다.
백프레셔: 생산자가 소비자보다 빠를 때 버퍼·큐·스트림에서 속도를 줄이는 신호를 어디에 둘지 정의합니다.

프로덕션 운영 패턴

영역	운영 관점 질문
관측성	요청 단위 상관 ID, 에러율·지연 p95/p99, 의존성 타임아웃·재시도가 대시보드에 보이는가
안전성	입력 검증·권한·비밀·감사 로그가 코드 경로마다 일관적인가
신뢰성	재시도는 멱등 연산에만 적용되는가, 서킷 브레이커·백오프·DLQ가 있는가
성능	캐시·배치 크기·커넥션 풀·인덱스·백프레셔가 데이터 규모에 맞는가
배포	롤백 룬북, 카나리/블루그린, 마이그레이션·피처 플래그가 문서화되어 있는가
용량	피크 트래픽·디스크·FD·스레드 풀 상한을 주기적으로 검증하는가

스테이징은 데이터 양·네트워크 RTT·동시성을 프로덕션에 가깝게 맞출수록 재현율이 올라갑니다.

확장 예시: 엔드투엔드 미니 시나리오

앞선 본문 주제(「[2026] REST API 완전 가이드 — HTTP 의미론·리처드슨 성숙도·HATEOAS·버전·프로덕션」)를 배포·운영 흐름에 맞춰 옮긴 체크리스트입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.

입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드를 경계에 둔다.
핵심 경로 계측: 요청 ID, 단계별 지연, 외부 호출 결과 코드를 로그·메트릭·트레이스에서 한 흐름으로 본다.
실패 주입: 의존성 타임아웃·5xx·부분 데이터·락 대기를 스테이징에서 재현한다.
호환·롤백: 설정/마이그레이션/클라이언트 버전을 되돌릴 수 있는지 확인한다.
부하 후 검증: 피크 대비 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·힙/FD 스냅샷 비교
빌드·배포만 실패	환경 변수, 권한, 플랫폼 차이, lockfile	CI 로그와 로컬 diff, 런타임·이미지 버전 핀
설정 불일치	프로필·시크릿·기본값, 리전	스키마 검증된 설정 단일 소스와 배포 매트릭스 표준화
데이터 불일치	비멱등 재시도, 부분 쓰기, 캐시 무효화 누락	멱등 키·아웃박스·트랜잭션 경계 재검토

권장 순서: (1) 최소 재현 (2) 최근 변경 범위 축소 (3) 환경·의존성 차이 (4) 관측으로 가설 검증 (5) 수정 후 회귀·부하 테스트.

배포 전에는 git add → git commit → git push 후 npm run deploy 순서를 권장합니다.