Next.js를 주력으로 사용하고 있기에 늘상 RESTful API를 만들어서 사용하고 있었음에도, 누군가 RESTful API에 대해 이론적인 질문을 했을때 명확한 답을 내놓지 못하는 일을 겪어서 이론적인 내용도 정리를 해볼까 하여 작성하게 되었습니다.
자주 사용하는 기술을 제대로 알고 사용하는것 역시 중요한 일이라고 생각하게 된 계기였으며, 때때로는 이런 디테일의 차이가 실력의 차이를 만들기도 한다고 생각합니다.
AI를 이용해 코드를 작성하더라도 프롬프트를 쥐고있는 개발자의 배경지식에 따라 완전히 다른 결과물이 나오는것처럼요"
1. REST의 기본 원칙
RESTful API는 다음과 같은 원칙을 따릅니다.
클라이언트-서버 구조 (Client-Server)
클라이언트(예: 프론트엔드)와 서버(백엔드)를 분리하여 독립적으로 개발 및 운영할 수 있습니다.
무상태성 (Stateless)
각 요청(Request)은 독립적으로 처리되며, 서버는 이전 요청의 상태를 저장하지 않습니다. 클라이언트가 필요한 정보를 요청에 포함해야 합니다.
캐시 가능 (Cacheable)
API 응답을 캐싱하여 성능을 최적화할 수 있습니다.
일관된 인터페이스 (Uniform Interface)
HTTP 표준을 따르고, 리소스 중심으로 URL을 설계해야 합니다.
계층화된 시스템 (Layered System)
프록시, 로드 밸런서 등 다양한 계층을 추가할 수 있으며, 클라이언트는 이를 인지할 필요가 없습니다.
2. RESTful API의 특징
RESTful API는 리소스(Resource) 중심 설계를 따르며, 일반적으로 JSON 형식으로 데이터를 주고받습니다.
(1) HTTP 메서드(Methods)
HTTP 메서드역할설명 | ||
GET | 조회(Read) | 리소스 정보를 가져옴 |
POST | 생성(Create) | 새로운 리소스를 생성 |
PUT | 수정(Update) | 기존 리소스를 전체 수정 |
PATCH | 부분 수정(Update) | 기존 리소스를 일부 수정 |
DELETE | 삭제(Delete) | 리소스를 삭제 |
(2) RESTful URL 설계
좋은 예시 (RESTful)
GET /users → 모든 사용자 조회
GET /users/{id} → 특정 사용자 조회
POST /users → 새로운 사용자 추가
PUT /users/{id} → 특정 사용자 정보 수정
DELETE /users/{id} → 특정 사용자 삭제나쁜 예시 (비RESTful)
GET /getUser?id=1 → 동작(Verb)이 포함된 URL
POST /createUser → 동작이 URL에 포함됨
PUT /updateUser?id=1 → URL이 비일관적
DELETE /deleteUser?id=1 → 동작이 포함됨3. RESTful API의 장단점
장점
클라이언트-서버 분리로 인해 확장성이 뛰어남
HTTP 표준을 준수하여 다양한 환경(웹, 모바일 등)에서 사용 가능.
또한 일관된 인터페이스 덕분에 이해하기 쉽고 유지보수가 용이함.
단점
무상태성으로 인해 요청마다 필요한 데이터를 포함해야 하므로 오버헤드 발생 가능
실시간 데이터 업데이트에는 WebSocket보다 비효율적일 수 있음.
한 번의 요청으로 많은 데이터를 가져오기 어렵고, 여러 번 요청해야 할 수도 있음.
4. RESTful API 예제 (Express.js)
const express = require('express');
const app = express();
app.use(express.json());
let users = [
{ id: 1, name: 'Alice' },
{ id: 2, name: 'Bob' }
];
// 모든 사용자 조회 (GET)
app.get('/users', (req, res) => {
res.json(users);
});
// 특정 사용자 조회 (GET)
app.get('/users/:id', (req, res) => {
const user = users.find(u => u.id === parseInt(req.params.id));
if (!user) return res.status(404).send('User not found');
res.json(user);
});
// 사용자 추가 (POST)
app.post('/users', (req, res) => {
const newUser = { id: users.length + 1, name: req.body.name };
users.push(newUser);
res.status(201).json(newUser);
});
// 사용자 수정 (PUT)
app.put('/users/:id', (req, res) => {
const user = users.find(u => u.id === parseInt(req.params.id));
if (!user) return res.status(404).send('User not found');
user.name = req.body.name;
res.json(user);
});
// 사용자 삭제 (DELETE)
app.delete('/users/:id', (req, res) => {
users = users.filter(u => u.id !== parseInt(req.params.id));
res.status(204).send();
});
app.listen(3000, () => console.log('Server running on port 3000'));5. RESTful API vs GraphQL
비교 항목 | RESTful API | GraphQL |
데이터 요청 방식 | 여러 개의 엔드포인트 사용 | 단일 엔드포인트 사용 |
데이터 반환 형식 | 정해진 JSON 구조 반환 | 필요한 데이터만 반환 |
오버페칭 문제 | 필요 없는 데이터까지 가져올 수 있음 | 클라이언트가 필요한 데이터만 요청 |
실시간 지원 | WebSocket 필요 | 기본적으로 Subscription 제공 |
6. RESTful API를 더 개선하는 방법
JWT 또는 OAuth를 활용한 인증(Authentication) 추가.
**Rate Limiting(요청 제한)**을 설정하여 API 남용 방지.
Swagger 같은 문서화 도구를 활용하여 API 명세 작성.
**캐싱(Cache-Control, Redis)**을 통해 성능 최적화.
결론
RESTful API는 리소스 중심 설계, 일관된 인터페이스, HTTP 표준 준수를 특징으로 하는 API 스타일입니다. REST의 원칙을 잘 따르면 확장성과 유지보수성이 뛰어난 API를 만들 수 있습니다.
하지만 실시간 데이터 업데이트가 필요하거나, 오버페칭 문제가 발생하는 경우 GraphQL 또는 WebSocket 같은 대안을 고려할 수도 있습니다.
RESTful API를 구축할 때는 일관된 URL 설계, HTTP 메서드의 적절한 활용, 성능 최적화 등을 고려하는 것이 중요합니다. 🚀