RESTful API

RESTful API를 “규칙”이 아니라 “스타일 가이드”로 받아들이고, HTTP 자체의 능력을 최대한 활용하면 플랫폼 의존성은 줄고 변경 대응 속도는 빨라집니다.

1️⃣ REST vs RESTful — 헷갈리지 말자

구분	REST	RESTful API
정의	분산 시스템 아키텍처 스타일	REST 제약(무상태·계층·캐시·통합 인터페이스 등)을 만족한 구현
적용 범위	개념·원칙	HTTP 기반 웹 API
평가 기준	6개 제약 충족 여부	Richardson Maturity Model (Level 2 이상)

REST는 ‘무상태’·‘캐시 가능’·‘계층화’ 등 아키텍처 제약을 가진 스타일이며, RESTful은 이를 따르는 구현이다 

• REST와 RESTful을 혼용하면, 단순히 “URL이 예쁘다”는 이유로 RESTful이라 오해하기 쉽다

2️⃣ 핵심 개념 정리

2‑1. Uniform Interface

• Resource : /posts, /users/1hyung — 식별 가능한 대상
• Representation : JSON, XML 등 — 상태를 전달하는 형식
• State Transfer : GET /posts/1, PATCH /posts/1 — HTTP 메서드로 상태 변경 / 조회
  REST는 무엇(리소스) 과 어떤 변화(메서드) 만 드러내고 구현은 숨긴다 

2‑2. Richardson Maturity Model

Level	특징	실무 의의
0	한 URI + POST — RPC	과거 SOAP
1	리소스 URI	일부 레거시
2	URI + 4대 메서드 (표준)	대부분의 웹 API
3	Hypermedia(HATEOAS)	링크 기반 자동 탐색

• Level 2만 지켜도 “RESTful”이라 부른다

3️⃣ URI·메서드·상태코드: 설계 체크리스트

3‑1. URI 규칙

규칙	예시 ✅	안티 패턴 ❌
복수형·소문자 명사	/orders	/getOrders
계층은 / 로 표현	/orders/99/items	/itemsOfOrder/99
trailing slash 제거	/users	/users/
하이픈 구분	/long-comments	/long_comments
식별자 노출	/users/1hyung	/users?id=1hyung
옵션은 Query	/orders?status=PAID&page=2	/orders/status/PAID

3‑2. HTTP 메서드 & 멱등성

메서드	의도	멱등성	근거
GET	Read	✅	RFC 9110 9.2.2
POST	Create	❌	동일 요청 시 리소스 중복
PUT	전체 수정	✅	RFC 9110
PATCH	부분 수정	설계자 정의	문서로 명시
DELETE	Delete	✅	RFC 9110

3‑3. 상태코드 스펙

범위	주로 사용	비고
2xx 성공	200 OK, 201 Created, 204 No Content	생성/삭제 구분
4xx 클라이언트 오류	400, 401, 403, 404, 422 Unprocessable Entity	422는 검증 오류 세분화
5xx 서버 오류	500, 502	시스템 장애 표시

에러 응답은 RFC 9457 Problem Details를 채택해 type/title/detail/instance를 표준화하면 디버깅 시간이 줄어든다