🟨 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배로 만든다.