🟨 2-11. REST API 완벽 이해 — CRUD와 RESTful 설계 원칙, 프론트엔드 관점에서의 API 구조
1. REST란 무엇인가
REST(Representational State Transfer)는
웹에서 리소스(데이터) 를 다루기 위한 표준화된 규칙 체계다.
즉, “서버와 클라이언트가 데이터를 주고받는 방식의 약속”이라고 생각하면 된다.
💡 예를 들어,
“게시글 목록을 가져온다” → GET /posts
“게시글 하나를 수정한다” → PUT /posts/1
“게시글을 삭제한다” → DELETE /posts/1
이런 방식이 바로 RESTful API 설계의 기본 철학이다.
2. REST의 6가지 원칙
1️⃣ 클라이언트-서버 구조
- 클라이언트(프론트엔드)와 서버(백엔드)가 명확히 분리되어야 한다.
- 프론트는 “화면”과 “상호작용”에 집중,
서버는 “데이터”와 “로직”에 집중한다.
2️⃣ 무상태성(Stateless)
- 서버는 요청 간 상태를 저장하지 않는다.
- 즉, 모든 요청은 독립적으로 처리되어야 한다.
✅ 예시: 로그인 시마다 토큰으로 인증 (세션 저장 X)
3️⃣ 캐시 가능(Cacheable)
- 동일한 요청 결과는 캐싱 가능해야 한다.
예: GET /posts는 캐싱 가능하지만, POST는 아님.
4️⃣ 일관된 인터페이스(Uniform Interface)
- API 구조가 일관되어야 한다.
/users는 사용자 리소스, /posts는 게시글 리소스 등.
5️⃣ 계층화 시스템(Layered System)
- 서버는 여러 계층(게이트웨이, 로드 밸런서 등)을 가질 수 있으나,
클라이언트는 그 구조를 몰라도 된다.
6️⃣ Code on Demand (Optional)
- 필요한 경우 서버에서 실행 가능한 코드를 내려줄 수도 있다.
(현대 REST API에서는 거의 사용되지 않는다.)
3. CRUD와 HTTP 메서드
REST API는 CRUD (Create, Read, Update, Delete) 를
HTTP 메서드와 일대일로 매칭한다.
동작 HTTP 메서드 예시 요청 설명
| 생성 | POST | POST /posts | 새 게시글 생성 |
| 조회 | GET | GET /posts | 전체 게시글 조회 |
| 조회(단일) | GET | GET /posts/1 | 특정 게시글 조회 |
| 수정 | PUT / PATCH | PUT /posts/1 | 게시글 수정 |
| 삭제 | DELETE | DELETE /posts/1 | 게시글 삭제 |
💡 PUT vs PATCH
- PUT: 전체 데이터 교체
- PATCH: 일부 데이터만 변경
4. RESTful한 URL 설계 규칙
좋은 API는 “읽기만 해도 의도를 알 수 있는” URL로 구성된다.
잘못된 예시 ❌ 올바른 예시 ✅ 설명
| /getUserInfo | /users/:id | 동작을 URL이 아닌 HTTP 메서드로 구분 |
| /createPost | /posts (POST) | URL에 동사를 쓰지 않음 |
| /updateUserInfo | /users/:id (PUT) | 리소스 중심 설계 |
| /deletePost?id=10 | /posts/10 (DELETE) | 명확한 리소스 식별자 사용 |
즉, REST API의 핵심은 명사형 URL + HTTP 메서드 조합이다.
5. 요청과 응답의 구조
✅ 요청(Request)
POST /users HTTP/1.1
Content-Type: application/json
{
"name": "기범",
"email": "kb@example.com"
}
✅ 응답(Response)
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": 101,
"name": "기범",
"email": "kb@example.com"
}
프론트엔드는 요청을 “JSON 형태로 보내고”,
응답을 “JSON 형태로 받는다”.
이때 HTTP 상태 코드를 반드시 확인해야 한다.
6. 주요 상태 코드 정리
코드 의미 설명
| 200 | OK | 요청 성공 |
| 201 | Created | 새 리소스 생성 |
| 204 | No Content | 성공했지만 응답 본문 없음 |
| 400 | Bad Request | 요청이 잘못됨 |
| 401 | Unauthorized | 인증 실패 |
| 403 | Forbidden | 접근 권한 없음 |
| 404 | Not Found | 리소스 없음 |
| 500 | Server Error | 서버 내부 오류 |
💡 프론트엔드는 상태 코드에 따라 알맞은 피드백을 제공해야 한다.
예: 401 → 로그인 만료, 404 → 페이지 없음, 500 → 서버 점검 중
7. RESTful 설계 예시
🎯 사용자(User) 리소스
기능 요청 방식 URL
| 전체 조회 | GET | /users |
| 단일 조회 | GET | /users/:id |
| 생성 | POST | /users |
| 수정 | PUT | /users/:id |
| 삭제 | DELETE | /users/:id |
🎯 게시글(Post) 리소스
기능 요청 방식 URL
| 전체 조회 | GET | /posts |
| 댓글 추가 | POST | /posts/:id/comments |
| 좋아요 처리 | PATCH | /posts/:id/like |
→ /posts/:id/comments 같은 중첩 리소스 구조를 Nested Resource 라고 한다.
8. REST API를 잘 설계하면 생기는 이점
- ✅ 프론트-백 분리 용이 → 협업 구조 명확
- ✅ API 문서 자동화 (Swagger, Postman) 가능
- ✅ React / Next.js / Vue 등 모든 프레임워크에서 재사용 가능
- ✅ 데이터 예측 가능성 향상 → 유지보수 쉬워짐
9. RESTful API와 GraphQL의 차이
항목 REST API GraphQL
| 데이터 구조 | 정해진 엔드포인트 | 원하는 데이터만 요청 가능 |
| 요청 수 | 여러 번 | 한 번에 가능 |
| 사용 복잡도 | 단순 | 상대적으로 복잡 |
| 캐싱 | 쉬움 | 추가 설정 필요 |
즉, GraphQL은 REST의 대체가 아니라 보완 관계에 있다.
대규모 프로젝트에서는 REST + GraphQL 혼용이 일반적이다.
10. 실무에서 자주 사용하는 REST 패턴
패턴 설명
| /auth/login | 로그인 |
| /auth/refresh | 토큰 재발급 |
| /users/me | 내 정보 가져오기 |
| /posts/:id/like | 좋아요 토글 |
| /search?q=keyword | 검색 기능 |
| /stats/daily | 통계 조회 |
이런 명명 규칙은 개발자들 사이에서 거의 “불문율”처럼 쓰인다.
11. REST API 문서 자동화 도구
- Swagger (OpenAPI) : 백엔드가 API 스펙을 정의하면 자동 문서화
- Postman : 프론트엔드에서 API 테스트 및 시뮬레이션
- Insomnia : 환경변수 기반 테스트 자동화 도구
💡 프론트엔드 개발자는 Swagger 문서를 읽을 수 있어야 한다.
이걸 이해하면 API 요청 구조를 정확히 예측할 수 있다.
12. 정리
개념 설명
| REST | 리소스 중심의 API 설계 방식 |
| RESTful | REST 원칙을 따르는 구조적 설계 |
| CRUD | Create, Read, Update, Delete |
| HTTP 메서드 | GET, POST, PUT, PATCH, DELETE |
| URL 규칙 | 명사형 + 계층적 구조 |
| 상태 코드 | 요청 결과를 명확히 전달 |
13. 마무리
이제 프론트엔드 개발자로서
“API를 사용”하는 수준을 넘어
“API 구조를 이해하고 협업하는” 단계에 도달했다.
REST는 단순한 규칙이 아니라,
프론트엔드와 백엔드가 언어를 공유하기 위한 약속이다.
잘 설계된 API는 개발 속도를 2배로,
잘못 설계된 API는 버그를 10배로 만든다.