REST API란? RESTful한 설계 원칙

REST API란? RESTful한 설계 원칙

1. REST API란?

 REST API(Representational State Transfer API)는 HTTP 프로토콜을 기반으로 클라이언트와 서버가 데이터를 주고받는 방식을 의미한다. REST는 웹의 아키텍처 스타일 중 하나로, 리소스(Resource) 중심으로 설계되어 있으며 간결하고 직관적인 URL과 HTTP 메서드를 활용하는 것이 특징이다.

 

📌 REST API의 주요 개념

• 리소스(Resource) → URI(Uniform Resource Identifier)로 표현됨 (/users, /posts/1 등)
• 행동(Method) → HTTP 메서드(GET, POST, PUT, DELETE 등) 사용
• 표현(Representation) → JSON, XML 등의 형식으로 데이터를 주고받음

📌 REST API의 주요 특징

• 클라이언트-서버 구조 → 클라이언트와 서버를 분리하여 확장성 증가
• 무상태성(Stateless) → 각 요청이 독립적으로 처리되며, 서버가 클라이언트의 상태를 저장하지 않음
• 캐싱 가능(Cacheable) → GET 요청 응답을 캐싱하여 성능 최적화 가능
• 계층적 구조(Layered System) → API가 프록시, 로드 밸런서를 통해 계층적으로 설계될 수 있음
• 일관된 인터페이스(Uniform Interface) → URL, HTTP 메서드를 일관되게 사용하여 가독성 향상

---

2. RESTful API란?

 RESTful API란 REST의 원칙을 잘 따르는 API를 의미한다. 즉, 리소스를 명확하게 구분하고, HTTP 메서드를 적절하게 활용하며, 일관된 응답 구조를 유지하는 API가 RESTful한 API라고 할 수 있다.

 

📌 RESTful한 API의 조건

• 명확한 리소스 경로 사용 (/users/1 → 특정 사용자 조회)
• HTTP 메서드의 적절한 활용 (GET, POST, PUT, DELETE 등)
• 응답 데이터 형식 통일 (JSON, XML)
• URI에 동사를 사용하지 않음 (예: /getUser ❌ → /users ⭕)

📌 RESTful하지 않은 예제

❌ GET /getUser?id=1
❌ POST /createUser
❌ PUT /modifyUser/1
❌ DELETE /removeUser/1

 

📌 RESTful한 예제

✅ GET /users/1  → 특정 사용자 조회
✅ POST /users  → 사용자 생성
✅ PUT /users/1  → 특정 사용자 정보 수정
✅ DELETE /users/1  → 특정 사용자 삭제

---

3. REST API의 HTTP 메서드

 REST API는 HTTP 메서드를 활용하여 리소스의 상태를 조작한다.

HTTP 메서드	역할
GET	리소스 조회
POST	리소스 생성
PUT	리소스 전체 수정
PATCH	리소스 일부 수정
DELETE	리소스 삭제

 

📌 HTTP 메서드 예제

GET /products        → 전체 상품 목록 조회
GET /products/1      → 특정 상품 조회
POST /products       → 새로운 상품 생성
PUT /products/1      → 특정 상품 정보 수정
DELETE /products/1   → 특정 상품 삭제

 

📌 PUT과 PATCH의 차이점

• PUT: 리소스의 전체 내용을 수정
• PATCH: 리소스의 일부 내용을 수정
  예를 들어, 사용자의 email 정보만 수정할 경우 PATCH를 사용한다.

---

4. REST API 응답 코드

  REST API는 HTTP 응답 코드를 활용하여 클라이언트에게 요청 처리 결과를 전달한다.

상태 코드	의미
200 OK	요청 성공 (데이터 조회, 수정 완료)
201 Created	리소스 생성 성공
204 No Content	요청 성공했지만 응답 본문 없음 (DELETE 요청)
400 Bad Request	잘못된 요청 (필수 파라미터 누락 등)
401 Unauthorized	인증 실패 (로그인 필요)
403 Forbidden	권한 없음
404 Not Found	요청한 리소스를 찾을 수 없음
500 Internal Server Error	서버 내부 오류

 

📌 예제 응답 (JSON)

{
  "status": 200,
  "message": "Success",
  "data": {
    "id": 1,
    "name": "iPhone 15",
    "price": 1200000
  }
}

---

5. RESTful API 설계 원칙

RESTful한 API를 설계할 때는 다음 원칙을 따르는 것이 중요하다.

 

1) 명확한 리소스 URI 사용

• URI는 리소스를 나타내야 하며, 동사를 포함하지 않아야 한다.

❌ GET /getUser?id=1
✅ GET /users/1

 

2) HTTP 메서드의 올바른 사용

• HTTP 메서드와 URI를 조합하여 리소스를 조작한다.

✅ POST /users  → 새 사용자 등록
✅ PUT /users/1  → 사용자 정보 전체 수정
✅ PATCH /users/1  → 사용자 정보 일부 수정
✅ DELETE /users/1  → 사용자 삭제

 

3) 일관된 응답 구조 유지

• JSON을 기본 응답 포맷으로 사용하고, 응답 데이터의 형식을 통일한다.

{
  "status": 200,
  "message": "Success",
  "data": {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com"
  }
}

 

4) 에러 응답 처리

• 오류가 발생할 경우 명확한 HTTP 상태 코드와 메시지를 제공한다.

{
  "status": 400,
  "error": "Bad Request",
  "message": "필수 필드 'email'이 누락되었습니다."
}

 

5) 버전 관리 (Versioning)

• API 변경 시 클라이언트의 혼란을 방지하기 위해 버전 관리를 적용한다.

✅ /api/v1/users
✅ /api/v2/users

---

6. REST API와 GraphQL 비교

 REST API 외에도 GraphQL이라는 대체 기술이 존재한다. 두 방식은 각기 다른 장단점을 가진다. 

비교 항목	REST API	GraphQL
데이터 요청 방식	여러 개의 엔드포인트 제공	하나의 엔드포인트 사용
데이터 응답 크기	필요 없는 데이터 포함 가능	클라이언트가 필요한 데이터만 요청
유연성	고정된 응답 구조	요청에 따라 응답 구조 변경 가능
성능	여러 요청이 필요할 수 있음	한 번의 요청으로 원하는 데이터 수집

📌 언제 REST API를 사용하고, 언제 GraphQL을 사용할까?

• REST API: 단순한 CRUD 기능이 필요할 때
• GraphQL: 다양한 데이터를 한 번에 요청해야 할 때

---

7. REST API 사용 예제

📌 Node.js + Express로 간단한 REST API 만들기

const express = require('express');
const app = express();
app.use(express.json());

let users = [{ id: 1, name: "Alice" }];

// 사용자 목록 조회
app.get('/users', (req, res) => {
    res.status(200).json(users);
});

// 새로운 사용자 추가
app.post('/users', (req, res) => {
    const newUser = { id: users.length + 1, name: req.body.name };
    users.push(newUser);
    res.status(201).json(newUser);
});

// 서버 실행
app.listen(3000, () => console.log('Server running on port 3000'));