API 설계 기본 원칙 (API Design Principles)
RESTful API 설계는 웹 서비스가 클라이언트와 서버 간의 상호 작용을 간단하고 일관되게 유지하는 데 중요한 역할을 합니다. 다음은 RESTful API 설계의 기본 원칙입니다.
- 자원 기반의 URI:
- URI는 자원을 나타내야 합니다. 예를 들어,
/users는 사용자 목록을,/users/1은 특정 사용자를 나타냅니다.
- HTTP 메서드 사용:
- GET: 데이터 조회
- POST: 데이터 생성
- PUT: 데이터 갱신
- DELETE: 데이터 삭제
- 상태 없는 서버:
- 각 요청은 독립적으로 처리되어야 하며, 서버는 요청 간의 상태를 저장하지 않아야 합니다.
- 표현 방식:
- JSON을 주로 사용하지만 XML, YAML 등 다른 표현 방식도 사용 가능합니다.
- 일관된 응답 구조:
- 응답 데이터 구조는 일관되게 유지하여 클라이언트가 쉽게 이해하고 사용할 수 있도록 합니다.
예제
const express = require('express');
const app = express();
app.use(express.json());
let users = [
{ id: 1, name: 'Alice' },
{ id: 2, name: 'Bob' }
];
// 사용자 목록 조회
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 };
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;
res.json(user);
});
// 사용자 삭제
app.delete('/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');
users = users.filter(u => u.id !== parseInt(req.params.id));
res.json(user);
});
app.listen(3000, () => {
console.log('Server is running on port 3000');
});
API 문서 작성 (API Documentation with Swagger/OpenAPI)
API 문서는 클라이언트 개발자가 API를 이해하고 사용하는 데 필수적입니다. Swagger는 API 문서화를 위한 도구입니다.
Swagger 설치 및 설정
npm install swagger-ui-express swagger-jsdoc
예제 코드
const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');
const options = {
definition: {
openapi: '3.0.0',
info: {
title: 'Sample API',
version: '1.0.0',
},
},
apis: ['./app.js'], // API 문서 경로
};
const specs = swaggerJsdoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
/**
* @swagger
* /users:
* get:
* summary: Retrieves a list of users
* responses:
* 200:
* description: A list of users
*/
app.get('/users', (req, res) => {
res.json(users);
});
Postman을 사용한 API 테스트 (API Testing with Postman)
Postman은 API 테스트를 위한 강력한 도구입니다.
- Postman 설치:
- Postman 공식 사이트에서 다운로드 및 설치합니다.
- 테스트 실행:
- Postman을 실행하고, 새로운 요청을 생성합니다.
- 요청 유형(GET, POST, PUT, DELETE 등)을 선택하고, URL을 입력합니다.
- 필요한 경우, 헤더 및 바디를 설정합니다.
Send버튼을 눌러 요청을 전송하고 응답을 확인합니다.
테스트 주도 개발(TDD) 소개 및 Jest 사용법 (Test-Driven Development with Jest)
테스트 주도 개발(TDD)은 코드를 작성하기 전에 테스트를 먼저 작성하는 개발 방법론입니다. Jest는 JavaScript 테스트 프레임워크로, Node.js 애플리케이션에서 TDD를 실천하는 데 유용합니다.
Jest 설치 및 설정
npm install jest
package.json 파일을 다음과 같이 수정하여 Jest를 실행합니다.
{
"scripts": {
"test": "jest"
}
}
예제 테스트 코드
// sum.js
function sum(a, b) {
return a + b;
}
module.exports = sum;
// sum.test.js
const sum = require('./sum');
test('adds 1 + 2 to equal 3', () => {
expect(sum(1, 2)).toBe(3);
});
Jest 테스트를 실행합니다.
npm test
API 테스트 예제
const request = require('supertest');
const express = require('express');
const app = express();
app.use(express.json());
let users = [
{ id: 1, name: 'Alice' },
{ id: 2, name: 'Bob' }
];
app.get('/users', (req, res) => {
res.json(users);
});
describe('GET /users', () => {
it('should return all users', async () => {
const res = await request(app).get('/users');
expect(res.statusCode).toEqual(200);
expect(res.body.length).toBe(2);
});
});
app.listen(3000, () => {
console.log('Server is running on port 3000');
});
이 문서에서는 Node.js를 사용한 RESTful API 개발과 테스트의 다양한 측면을 다루었습니다. API 설계 기본 원칙, Swagger를 사용한 API 문서 작성, Postman을 사용한 API 테스트, 그리고 Jest를 사용한 테스트 주도 개발을 상세하게 설명하고, 다양한 예제를 제공하였습니다. 이를 통해 RESTful API 개발과 테스트에 필요한 기술을 습득할 수 있습니다.