[RESTful API] 웹 서비스를 설계하는 가장 보편적인 방식

728x90

RESTful API 

웹 개발을 하다 보면 "REST API", "RESTful 설계", "HTTP 메서드" 같은 용어를 자주 접하게 됩니다. 이 글에서는 웹에서 데이터를 주고받는 표준적인 방식 중 하나인 RESTful API에 대해 자세히 알아보겠습니다. REST의 개념부터 RESTful하게 API를 설계하는 방법, 그리고 예제 코드까지 포함하여 RESTful API를 처음 접하는 개발자도 쉽게 이해할 수 있도록 설명합니다.

 

---

1.  REST란 무엇인가?

REST는 REpresentational State Transfer의 약자로, 2000년 로이 필딩(Roy Fielding)의 박사 논문에서 처음 소개된 웹 아키텍처 스타일입니다. 핵심은 리소스(Resource)를 URI로 표현하고, 그 리소스를 조작하는 행위를 HTTP 메서드로 표현하는 것입니다.

REST의 6가지 아키텍처 제약 조건

1. 클라이언트-서버 구조 : 클라이언트와 서버는 서로 독립적으로 동작해야 합니다.
2. 무상태성(Stateless) : 서버는 요청 간의 상태를 저장하지 않아야 합니다.
3. 캐시 처리 가능(Cacheable) : 응답은 캐싱이 가능해야 하며, 이를 통해 성능을 개선할 수 있습니다.
4. 계층화된 시스템 : 클라이언트는 중간 서버가 있더라도 이를 알 필요가 없습니다.
5. 인터페이스 일관성(Uniform Interface) : API 설계는 일관된 인터페이스를 가져야 합니다.
6. 코드 온 디맨드(선택 사항) : 서버는 클라이언트에게 실행 가능한 코드를 보낼 수 있습니다 (예: JavaScript).

 

---

2.  RESTful API란?

RESTful API란 위의 REST 원칙을 따르는 API를 의미합니다. RESTful하게 API를 설계한다는 것은 리소스를 명확하게 정의하고, HTTP 메서드를 알맞게 사용하는 것을 의미합니다.

HTTP 메서드와 역할

메서드	역할	예시
GET	리소스 조회	GET /users
POST	리소스 생성	POST /users
PUT	리소스 전체 수정	PUT /users/1
PATCH	리소스 부분 수정	PATCH /users/1
DELETE	리소스 삭제	DELETE /users/1

RESTful API URI 설계 예시

GET /articles           # 전체 게시글 조회
GET /articles/10        # ID가 10인 게시글 조회
POST /articles          # 새 게시글 작성
PUT /articles/10        # 게시글 10번 전체 수정
PATCH /articles/10      # 게시글 10번 일부 수정
DELETE /articles/10     # 게시글 10번 삭제

RESTful하지 않은 예

POST /createArticle     # 비표준적 메서드 사용
GET /getUserById?id=10  # 동사 기반 URI

• RESTful 설계에서는 URI는 리소스를 나타내고, 동사는 HTTP 메서드로 표현하는 게 핵심입니다.

 

---

3.  예제 코드

Node.js의 Express 프레임워크를 사용해 간단한 사용자 API를 만들어보겠습니다.

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

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

app.get('/users', (req, res) => {
  res.json(users);
});

app.post('/users', (req, res) => {
  const newUser = { id: Date.now(), ...req.body };
  users.push(newUser);
  res.status(201).json(newUser);
});

app.get('/users/:id', (req, res) => {
  const user = users.find(u => u.id == req.params.id);
  if (!user) return res.status(404).send('User not found');
  res.json(user);
});

app.listen(3000, () => console.log('Server started'));

 

RESTful API 설계 시 유의할 점

• 명사 기반 URI를 사용하세요. (/users, /products)
• HTTP 상태 코드를 정확히 사용하세요. (200 OK, 201 Created, 404 Not Found, 400 Bad Request 등)
• 계층적 구조를 반영한 URI 설계를 고려하세요. (/users/1/posts)
• 버전 관리를 고려하세요. (/api/v1/users)

 

---

4.  마무리

RESTful API의 핵심 요약

• REST는 웹 리소스를 다루기 위한 아키텍처 스타일입니다.
• RESTful API는 REST 원칙에 따라 설계된 API입니다.
• HTTP 메서드와 URI는 일관성 있고 명확하게 설계해야 합니다.
• RESTful한 설계는 확장성과 유지보수성에 매우 유리합니다.

함께 보면 좋은 자료

외부 사이트 :

• MDN Web Docs - REST
• 위키백과 - REST 
• Learn REST API Design

블로그 글 :

[HTTP 메소드] 웹의 동작 방식을 이해하는 첫걸음

[HTTP 상태 코드] 웹 통신의 응답 언어를 이해하자.

 

---