REST API 완벽 정리 — 개념, 설계 원칙, HTTP 메서드, 실전 예제까지 한방에

REST API 완벽 정리

REST API는 웹 개발자라면 반드시 알아야 할 핵심 기술이다. 하지만 "REST가 뭐예요?" 하고 물으면 제대로 설명할 수 있는 사람은 의외로 적다.

이 글에서는 REST의 개념부터 설계 원칙, HTTP 메서드, URI 설계 규칙, 실전 예제까지 한 번에 정리한다.

---

REST란 무엇인가

REST(Representational State Transfer)는 2000년에 로이 필딩(Roy Fielding)이 박사 논문에서 제안한 아키텍처 스타일이다.

쉽게 말해, 웹에서 자원(Resource)을 HTTP 방식으로 다루는 표준화된 방법이라고 생각하면 된다.

핵심 구성 요소는 세 가지다.

요소	설명	예시
자원(Resource)	URI로 표현	/users, /posts/1
행위(Verb)	HTTP 메서드 사용	GET, POST, PUT, DELETE
표현(Representation)	자원의 상태를 JSON/XML로 전달	{ "name": "홍길동" }

---

REST의 6가지 제약 조건

REST를 단순히 "URL로 CRUD 하는 것"으로 이해하면 절반만 아는 것이다. REST 아키텍처에는 6가지 제약 조건이 있다.

1. 클라이언트-서버 구조 (Client-Server)

클라이언트와 서버의 역할을 분리한다. 클라이언트는 UI를, 서버는 데이터 처리를 담당한다. 덕분에 각각 독립적으로 발전할 수 있다.

2. 무상태 (Stateless)

서버는 클라이언트의 상태를 저장하지 않는다. 모든 요청은 그 자체로 완전한 정보를 포함해야 한다. 세션 정보를 서버에 저장하지 않으므로 확장(Scale-out)에 유리하다.

3. 캐시 처리 가능 (Cacheable)

응답 데이터는 캐싱이 가능해야 한다. HTTP의 Cache-Control, ETag 같은 헤더를 활용하여 불필요한 요청을 줄일 수 있다.

4. 계층화 시스템 (Layered System)

클라이언트는 최종 서버에 직접 연결됐는지, 중간 서버(프록시, 로드밸런서)를 거치는지 알 수 없다. 이를 통해 보안, 로드밸런싱, 캐싱 등을 투명하게 추가할 수 있다.

5. 인터페이스 일관성 (Uniform Interface)

URI, HTTP 메서드, 응답 형식 등이 일관적이어야 한다. REST에서 가장 중요한 제약 조건이다.

6. Code on Demand (선택)

서버가 클라이언트에게 실행 가능한 코드(JavaScript 등)를 전달할 수 있다. 유일한 선택적 제약 조건이다.

---

HTTP 메서드 완벽 정리

REST API에서 행위(Verb)는 HTTP 메서드로 표현한다. 각 메서드의 역할과 특성을 정확히 이해하는 것이 중요하다.

GET — 조회

GET /users/1

• 목적: 리소스 조회
• 특징: URL에 파라미터 포함(?name=kim), 데이터 변경 없음, 캐시 가능
• 사용 예시: 게시글 목록 조회, 유저 정보 조회

POST — 생성

POST /users
Content-Type: application/json

{ "name": "홍길동", "email": "hong@example.com" }

• 목적: 리소스 생성
• 특징: Body에 데이터 전송, 서버 상태 변경, 재요청 시 중복 생성 주의
• 사용 예시: 회원가입, 글 작성, 댓글 등록

PUT — 전체 수정

PUT /users/1
Content-Type: application/json

{ "name": "김철수", "email": "kim@example.com" }

• 목적: 리소스 전체 교체
• 특징: 리소스의 모든 필드를 보내야 함. 일부만 보내면 나머지 필드가 null/기본값이 될 수 있음
• 사용 예시: 회원 정보 전체 수정

PATCH — 부분 수정

PATCH /users/1
Content-Type: application/json

{ "email": "new@example.com" }

• 목적: 리소스 부분 수정
• 특징: 변경할 필드만 보내면 됨
• 사용 예시: 이메일만 변경, 비밀번호만 변경

DELETE — 삭제

DELETE /users/1

• 목적: 리소스 삭제
• 특징: 보통 Body 없이 URI로 대상 지정
• 사용 예시: 회원 탈퇴, 게시글 삭제

메서드 특성 비교표

메서드	목적	Body	멱등성	안전성	캐시
GET	조회	X	O	O	O
POST	생성	O	X	X	X
PUT	전체 수정	O	O	X	X
PATCH	부분 수정	O	X	X	X
DELETE	삭제	X	O	X	X

멱등성(Idempotent): 같은 요청을 여러 번 보내도 결과가 같은 성질. GET(조회 결과 동일), PUT(같은 값으로 덮어쓰기), DELETE(이미 삭제된 걸 다시 삭제)는 멱등적이다.
안전성(Safe): 서버 상태를 변경하지 않는 성질. GET만 안전하다.

---

GET vs POST 핵심 차이

면접에서 자주 나오는 질문이니 따로 정리한다.

구분	GET	POST
데이터 위치	URL 쿼리 파라미터	HTTP Body
보안	URL 노출 → 취약	Body에 포함 → 상대적 안전
데이터 크기	URL 길이 제한 있음	제한 거의 없음
캐싱	가능	기본적으로 불가
즐겨찾기	가능	불가
용도	조회	생성/변경

GET  /login?id=abcd&pw=1234     ← URL에 비밀번호 노출! 위험
POST /login (Body: id=abcd&pw=1234)  ← Body에 포함, 상대적 안전

---

URI 설계 규칙 (RESTful하게 만드는 법)

REST API가 "RESTful"하려면 URI 설계에 일관된 규칙이 필요하다.

기본 규칙

✅ 좋은 예
GET    /users          → 전체 사용자 조회
GET    /users/1        → 1번 사용자 조회
POST   /users          → 사용자 생성
PUT    /users/1        → 1번 사용자 수정
DELETE /users/1        → 1번 사용자 삭제

❌ 나쁜 예
GET    /getUser?id=1   → 동사 사용
POST   /createUser     → 동사 사용
GET    /User/1         → 대문자 사용

핵심 규칙 정리

규칙	좋은 예	나쁜 예
명사를 사용	/users	/getUsers
복수형 사용	/users	/user
소문자 사용	/users	/Users
하이픈 사용	/user-profiles	/user_profiles
행위는 HTTP 메서드로	DELETE /users/1	POST /deleteUser/1
계층 관계 표현	/users/1/posts	/getUserPosts?id=1

상태코드와 함께 쓰기

상황	메서드	상태코드
조회 성공	GET	200 OK
생성 성공	POST	201 Created
수정 성공	PUT/PATCH	200 OK
삭제 성공	DELETE	204 No Content
잘못된 요청	-	400 Bad Request
인증 필요	-	401 Unauthorized
권한 없음	-	403 Forbidden
리소스 없음	-	404 Not Found

---

실전 예제: 게시판 API 설계

[게시글]
GET    /api/posts              → 게시글 목록 조회
GET    /api/posts/1            → 1번 게시글 상세 조회
POST   /api/posts              → 게시글 작성
PUT    /api/posts/1            → 1번 게시글 전체 수정
PATCH  /api/posts/1            → 1번 게시글 부분 수정
DELETE /api/posts/1            → 1번 게시글 삭제

[댓글 - 게시글의 하위 자원]
GET    /api/posts/1/comments   → 1번 게시글의 댓글 목록
POST   /api/posts/1/comments   → 1번 게시글에 댓글 작성
DELETE /api/posts/1/comments/5 → 5번 댓글 삭제

[검색/필터링]
GET    /api/posts?page=1&size=20           → 페이징
GET    /api/posts?sort=createdAt,desc      → 정렬
GET    /api/posts?keyword=spring&category=java → 검색

---

REST API vs RESTful API

엄밀히 말하면, REST의 6가지 제약 조건을 모두 만족하는 API만 "RESTful"하다고 할 수 있다. 하지만 현실에서 모든 조건을 완벽히 지키는 API는 드물다.

대부분의 웹 API는 "REST 스타일을 따르는 HTTP API"에 가깝다. 그래도 업계에서는 관례적으로 "REST API"라고 부른다.

실무에서 중요한 건 용어가 아니라, 일관된 URI 설계 + 적절한 HTTP 메서드 사용 + 명확한 상태코드 응답을 지키는 것이다.

---

마무리 체크리스트

• REST의 핵심 3요소(자원, 행위, 표현)를 설명할 수 있는가?
• 6가지 제약 조건 중 "무상태"와 "인터페이스 일관성"을 설명할 수 있는가?
• GET, POST, PUT, PATCH, DELETE의 차이를 표로 정리할 수 있는가?
• 멱등성과 안전성이 무엇인지, 어떤 메서드가 해당하는지 아는가?
• URI를 RESTful하게 설계하는 규칙 5가지를 말할 수 있는가?
• GET vs POST의 차이를 보안·캐싱·데이터 위치로 구분할 수 있는가?