REST API

REST API 개념 및 특징

**REST(Representational State Transfer)**는 서버와 클라이언트가 자원(Resource)을 주고받는 방식에 대한 설계 원칙이다. REST 원칙을 따르는 API를 REST API(또는 RESTful API)라고 부른다.

핵심 아이디어 — 자원을 URL로, 행위를 HTTP 메서드로

REST의 가장 중요한 개념은 “무엇을 할 것인가(행위)“와 “무엇에 대해 할 것인가(자원)“를 분리하는 것이다.

GET /users        → users라는 자원을 조회한다
DELETE /users/1   → id가 1인 user 자원을 삭제한다

URL(엔드포인트)은 오직 “자원이 무엇인지”만 나타내고, “이 자원으로 무엇을 할지”는 HTTP 메서드가 담당한다. 그래서 REST API를 설계할 때는 URL에 동사를 쓰지 않는 게 원칙이다.

❌ GET  /getUsers
❌ POST /createUser
 
✅ GET  /users
✅ POST /users

REST의 주요 특징

• 무상태성 (Stateless): 서버는 클라이언트의 이전 요청 상태를 따로 저장하지 않는다. 매 요청마다 그 요청을 처리하는 데 필요한 모든 정보(인증 토큰 등)가 함께 전달되어야 한다.
• 자원의 표현 (Representation): 서버의 자원은 보통 JSON이나 XML 같은 형태로 표현되어 클라이언트에 전달된다. 요즘은 대부분 JSON을 사용한다.
• 일관된 인터페이스 (Uniform Interface): 자원은 URI로 식별하고, HTTP 메서드로 행위를 표현하는 일관된 방식을 따른다.
• 계층화 (Layered System): 클라이언트는 서버와 직접 통신하는지, 중간에 다른 서버(로드밸런서, 캐시 서버 등)를 거치는지 알 필요가 없다. 실무에서는 “완벽한 REST”보다 “REST스러운” API가 많다

REST 원칙을 엄격하게 100% 지키는 API는 생각보다 드물다. 대부분의 실무 API는 REST의 핵심 아이디어(자원 중심 URL + HTTP 메서드로 행위 표현)를 따르면서, 팀이나 서비스 상황에 맞게 일부 규칙을 유연하게 적용한다.

HTTP 메서드 (GET, POST, PUT, PATCH, DELETE)

GET    /users/1   → id가 1인 사용자 조회
POST   /users     → 사용자 생성 (body에 데이터)
PUT    /users/1   → id가 1인 사용자 전체 교체
PATCH  /users/1   → id가 1인 사용자 일부만 수정
DELETE /users/1   → id가 1인 사용자 삭제

PUT vs PATCH: PUT은 자원 전체를 새 데이터로 덮어쓰고, PATCH는 일부 필드만 부분 수정한다.

멱등성이란 같은 요청을 여러 번 보내도 결과가 같은 성질이다. PATCH와 POST는 호출할 때마다 결과가 달라질 수 있어 멱등하지 않다.

요청(Request) / 응답(Response) 구조

요청 구성 요소

POST /users HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...
 
{ "name": "gori", "age": 20 }

• Method: GET, POST 등
• Headers: 부가 정보 (인증 토큰, 데이터 형식 등)
• Body: 서버로 보낼 데이터 응답 구성 요소

HTTP/1.1 200 OK
Content-Type: application/json
 
{ "id": 1, "name": "gori", "age": 20 }

자주 보는 상태 코드

“비동기” 글에서 다룬 response.ok는 상태 코드가 2xx일 때만 true가 된다.

const response = await fetch("https://api.example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "gori", age: 20 })
});