REST란?
Representational State Transfer 의 약자로 소프트웨어 프로그램 개발의 아키텍처의 한 형식입니다. Roy Fielding의 박사학위 논문에서 최초로 소개되었다. 간단히 URL로 리소스에 대한 행위를 정의한다는 뜻이다.
RESTful
REST는 위 정의들을 구현하는 방식에 제약을 두지 않기 때문에 구체적인 가이드라인이 없습니다. 하지만 RESTful이라는 개념을 통해 그 가이드라인이 제시됩니다. RESTful는 REST를 REST답게 쓰기 위한 방법으로 누군가가 공식적으로 발표한 것이 아니라 여러 개발자들이 비공식적으로 의견을 제시한 것들로 명확한 정의는 없습니다. 즉 개발자마다 생각하는 RESTful의 내용이 다르다는 것이죠. 하지만 RESTful의 목적은 명확합니다. 이해하기 쉽고 사용하기 쉬운 REST API를 만드는 것입니다.
| CRUD | HTTP verbs | Route |
|---|---|---|
| 목록들 표시 | GET | /resource |
| 하나의 내용 표시 | GET | /resouce/:id |
| 생성 | POST | /resource |
| 수정 | PUT | /resouce/:id |
| 삭제 | DELETE | /resouce/:id |
예제:
- student를 생성하는 route은 POST /students
- id가 13인 student를 삭제하는 route은 DELETE /students/13
RESTful하지 못한 예:
- CRUD(생성,조회,수정,삭제)기능을 모두 POST로만 처리하는 API
- Route에 resource, id 외 정보가 들어가는 경우 (/students/updateName, student 하나의 이름만 변경하는 API의 경우 PUT students/:id/name이 되어야 합니다.)
2026 기준 REST API 설계 권장 사항
HTTP 메서드 세분화
GET /api/v1/students - 목록 조회
GET /api/v1/students/{id} - 단건 조회
POST /api/v1/students - 생성
PUT /api/v1/students/{id} - 전체 수정
PATCH /api/v1/students/{id} - 부분 수정
DELETE /api/v1/students/{id} - 삭제
상태 코드 활용
200 OK - 성공
201 Created - 생성 성공 (Location 헤더 포함)
204 No Content - 삭제 성공
400 Bad Request - 잘못된 요청
401 Unauthorized - 인증 필요
403 Forbidden - 권한 없음
404 Not Found - 리소스 없음
409 Conflict - 리소스 충돌
500 Internal Error - 서버 오류
페이징/정렬/필터링
GET /api/v1/students?page=1&size=20&sort=name,asc&grade=3
API 버저닝
/api/v1/students - URL 버저닝 (권장)
Header: Accept: application/vnd.api.v1+json - 헤더 버저닝
OpenAPI/Swagger 문서화
openapi: 3.0.0
paths:
/api/v1/students:
get:
summary: 학생 목록 조회
responses:
'200':
description: 성공