REST API는 "Representational State Transfer Application Programming Interface"의 약자로, 웹 서비스와 애플리케이션이 서로 통신하기 위해 사용하는 일련의 규칙과 관행입니다. REST API는 HTTP 프로토콜을 기반으로 하며, 웹 표준을 따르기 때문에 매우 인기가 있습니다. 여기서는 REST API의 주요 개념과 원칙을 설명하겠습니다.
1. REST의 기본 원칙
REST는 다음과 같은 몇 가지 주요 원칙을 따릅니다.
1.
클라이언트-서버 구조: 클라이언트와 서버는 서로 독립적이며, 클라이언트는 사용자 인터페이스를 관리하고 서버는 데이터를 저장하고 처리합니다. 이를 통해 서로의 역할을 분리할 수 있습니다.
2.
무상태 (Stateless): 각 요청은 독립적이며, 요청 간의 상태가 서버에 저장되지 않습니다. 모든 요청은 필요한 모든 정보를 포함하여 보내야 합니다. 이는 서버의 단순성과 확장성을 높입니다.
3.
캐시 가능: 응답은 캐시될 수 있어야 합니다. HTTP의 캐시 제어 메커니즘을 사용하여 클라이언트가 응답을 캐시하고 재사용할 수 있게 합니다.
4.
계층화된 시스템: 클라이언트는 직접 서버와 통신하는 것처럼 보이지만, 실제로는 중간에 여러 계층이 있을 수 있습니다. 이는 보안, 로드 밸런싱, 캐싱 등을 가능하게 합니다.
5.
인터페이스 일관성: URI, HTTP 메서드, 상태 코드, 헤더 등 일관된 인터페이스를 제공하여 클라이언트와 서버 간의 상호작용을 표준화합니다.
6.
코드 온 디맨드 (옵션): 서버는 클라이언트에 코드를 전송하여 실행할 수 있습니다. 이는 클라이언트의 기능을 확장할 수 있게 합니다.
2. RESTful API의 구성 요소
RESTful API는 일반적으로 다음과 같은 HTTP 메서드를 사용하여 리소스를 조작합니다.
•
GET: 서버에서 리소스를 조회합니다.
•
POST: 서버에 새로운 리소스를 생성합니다.
•
PUT: 서버에 리소스를 업데이트합니다.
•
DELETE: 서버에서 리소스를 삭제합니다.
•
PATCH: 리소스의 부분 업데이트를 수행합니다.
3. URI (Uniform Resource Identifier)
RESTful API에서 리소스는 URI를 통해 고유하게 식별됩니다. URI는 리소스를 명확하게 식별하며, 일반적으로 다음과 같은 형식을 가집니다.
http://example.com/resources/{resource_id}
Arduino
복사
예를 들어, 사용자 리소스를 다루는 API의 경우 다음과 같은 URI를 가질 수 있습니다.
•
GET /users: 모든 사용자 목록 조회
•
GET /users/123: 특정 사용자 (ID: 123) 조회
•
POST /users: 새로운 사용자 생성
•
PUT /users/123: 특정 사용자 (ID: 123) 정보 업데이트
•
DELETE /users/123: 특정 사용자 (ID: 123) 삭제
4. HTTP 상태 코드
REST API는 클라이언트에게 요청의 결과를 나타내기 위해 표준 HTTP 상태 코드를 사용합니다. 중요한 상태 코드 몇 가지는 다음과 같습니다.
•
200 OK: 요청이 성공적으로 처리됨
•
201 Created: 리소스가 성공적으로 생성됨
•
204 No Content: 요청이 성공적으로 처리되었으나 반환할 내용이 없음
•
400 Bad Request: 잘못된 요청
•
401 Unauthorized: 인증 실패
•
403 Forbidden: 접근 권한 없음
•
404 Not Found: 리소스를 찾을 수 없음
•
500 Internal Server Error: 서버 내부 오류
5. REST API 설계의 모범 사례
1.
명확하고 직관적인 URI: 리소스를 명확히 식별하고, 직관적으로 이해할 수 있는 URI를 사용합니다.
2.
일관된 네이밍: URI와 HTTP 메서드의 일관성을 유지하여 사용자가 API를 쉽게 이해하고 사용할 수 있게 합니다.
3.
적절한 상태 코드 사용: 요청의 결과에 적합한 HTTP 상태 코드를 반환하여 클라이언트가 응답을 쉽게 해석할 수 있게 합니다.
4.
보안 고려: HTTPS를 사용하여 데이터를 암호화하고, 인증 및 권한 부여 메커니즘을 사용합니다.
5.
버전 관리: API의 버전을 명시적으로 관리하여 호환성을 유지합니다.
REST API는 이러한 원칙과 모범 사례를 따름으로써 클라이언트와 서버 간의 상호작용을 표준화하고, 확장 가능하며 유지 관리하기 쉬운 시스템을 구축하는 데 기여합니다.
Node.js를 사용하여 간단한 RESTful API를 구축하는 예제를 보여드리겠습니다. 이를 위해 Express.js 프레임워크를 사용할 것입니다. Express.js는 Node.js를 위한 간단하고 유연한 웹 애플리케이션 프레임워크입니다.
Node.js와 Express.js로 RESTful API 구축 예제
1.
프로젝트 설정
먼저, Node.js와 npm(Node Package Manager)이 설치되어 있어야 합니다. 그런 다음, 새로운 프로젝트를 설정합니다.
mkdir rest-api-example
cd rest-api-example
npm init -y
Shell
복사
1.
Express.js 설치
다음으로, Express.js를 설치합니다.
npm install express
Shell
복사
1.
기본 서버 설정
프로젝트 루트 디렉토리에 index.js 파일을 생성하고 다음과 같이 기본 서버를 설정합니다.
const express = require('express');
const app = express();
const PORT = process.env.PORT || 3000;
// JSON 파싱 미들웨어 설정
app.use(express.json());
// 기본 라우트 설정
app.get('/', (req, res) => {
res.send('Hello, World!');
});
// 서버 실행
app.listen(PORT, () => {
console.log(`Server is running on port ${PORT}`);
});
JavaScript
복사
1.
RESTful API 엔드포인트 생성
이제 사용자 리소스를 관리하는 RESTful API 엔드포인트를 추가해보겠습니다. 사용자는 메모리에 저장되는 간단한 배열로 관리하겠습니다.
const express = require('express');
const app = express();
const PORT = process.env.PORT || 3000;
app.use(express.json());
// 사용자 데이터를 저장하는 배열
let users = [];
// 모든 사용자 조회
app.get('/users', (req, res) => {
res.json(users);
});
// 특정 사용자 조회
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);
});
// 새로운 사용자 생성
app.post('/users', (req, res) => {
const user = {
id: users.length + 1,
name: req.body.name,
email: req.body.email
};
users.push(user);
res.status(201).json(user);
});
// 특정 사용자 업데이트
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;
user.email = req.body.email;
res.json(user);
});
// 특정 사용자 삭제
app.delete('/users/:id', (req, res) => {
const userIndex = users.findIndex(u => u.id === parseInt(req.params.id));
if (userIndex === -1) return res.status(404).send('User not found');
users.splice(userIndex, 1);
res.status(204).send();
});
app.listen(PORT, () => {
console.log(`Server is running on port ${PORT}`);
});
JavaScript
복사
1.
API 테스트
서버를 실행하고 API 엔드포인트를 테스트할 수 있습니다. 서버를 실행하려면 다음 명령을 사용합니다.
node index.js
Shell
복사
이제 브라우저 또는 Postman과 같은 API 클라이언트를 사용하여 다음 엔드포인트를 테스트할 수 있습니다.
•
GET /users: 모든 사용자 조회
•
GET /users/:id: 특정 사용자 조회
•
POST /users: 새로운 사용자 생성 (JSON 본문에 name과 email 필드를 포함)
•
PUT /users/:id: 특정 사용자 업데이트 (JSON 본문에 name과 email 필드를 포함)
•
DELETE /users/:id: 특정 사용자 삭제
이 예제는 기본적인 RESTful API의 동작을 설명하기 위한 것입니다. 실제 환경에서는 데이터베이스와의 연동, 입력 데이터 검증, 오류 처리, 인증 및 권한 관리 등을 추가로 구현해야 합니다.
안녕하세요
•
한국전자기술연구원 김영광입니다.
•
관련 기술 문의와 R&D 공동 연구 사업 관련 문의는 “glory@keti.re.kr”로 연락 부탁드립니다.
Hello
•
I'm Yeonggwang Kim from the Korea Electronics Research Institute.
•
For technical and business inquiries, please contact me at “glory@keti.re.kr”