Express.js와 함께하는 REST API 서버 개발 첫걸음

안녕하세요! 웹 개발의 세계에 오신 것을 환영합니다. 오늘은 Node.js의 가장 인기 있는 웹 프레임워크인 Express.js를 사용하여 REST API 서버를 만드는 과정을 차근차근 알아보겠습니다. 백엔드 개발이 처음이신 분들도 쉽게 따라 하실 수 있도록 기초부터 탄탄하게 설명해 드릴 테니 걱정 마세요!

1. REST API, 그게 뭔가요?

개발을 시작하기 전에, 우리가 만들 REST API가 무엇인지 간단히 짚고 넘어가겠습니다. REST(Representational State Transfer)는 웹 서비스 아키텍처 스타일의 하나로, 자원(Resource)을 URI(Uniform Resource Identifier)로 표현하고, 해당 자원에 대한 행위(Method)를 HTTP 메서드(GET, POST, PUT, DELETE 등)로 정의하는 방식입니다. 간단히 말해, 웹을 통해 데이터를 주고받기 위한 규칙들의 집합이라고 생각하시면 됩니다.

• GET: 데이터를 조회합니다. (예: 사용자 목록 보기)
• POST: 데이터를 생성합니다. (예: 새로운 사용자 추가)
• PUT / PATCH: 데이터를 수정합니다. (예: 사용자 정보 업데이트)
• DELETE: 데이터를 삭제합니다. (예: 사용자 삭제)

2. 개발 환경 준비하기

Express.js는 Node.js 런타임 환경에서 동작합니다. 따라서 가장 먼저 Node.js와 npm(Node Package Manager)이 설치되어 있어야 합니다. 터미널(Windows에서는 PowerShell 또는 cmd)을 열고 다음 명령어를 실행하여 설치 여부를 확인하세요.

node -v
npm -v

만약 버전이 출력되지 않는다면, Node.js 공식 웹사이트에서 LTS 버전을 다운로드하여 설치해 주세요.

3. 프로젝트 시작: Express 설치

이제 본격적으로 프로젝트를 시작해 보겠습니다. 원하는 위치에 프로젝트 폴더를 만들고, 해당 폴더로 이동한 뒤 npm 프로젝트를 초기화합니다.

mkdir my-express-api
cd my-express-api
npm init -y

npm init -y 명령어는 package.json 파일을 기본값으로 생성해 줍니다. 이제 Express를 설치할 차례입니다.

npm install express

설치가 완료되면 package.json 파일과 node_modules 폴더, package-lock.json 파일이 생성된 것을 볼 수 있습니다.

4. 가장 간단한 Express 서버 만들기

이제 코드 에디터(VS Code 추천!)를 열고, 프로젝트 루트에 index.js 파일을 생성한 뒤 다음 코드를 작성해 보세요.

const express = require('express'); // express 모듈을 가져옵니다.
const app = express(); // express 애플리케이션을 생성합니다.
const port = 3000; // 서버를 실행할 포트 번호를 정의합니다.

// 루트 경로('/')에 대한 GET 요청을 처리합니다.
app.get('/', (req, res) => {
  res.send('Hello, Express World!');
});

// 정의된 포트에서 서버를 실행하고, 실행되면 콘솔에 메시지를 출력합니다.
app.listen(port, () => {
  console.log(`Server is running at http://localhost:${port}`)
});

코드를 저장한 뒤, 터미널에서 다음 명령어로 서버를 실행합니다.

node index.js

Server is running at http://localhost:3000 메시지가 보이면 성공입니다! 이제 웹 브라우저를 열고 http://localhost:3000으로 접속해 보세요. "Hello, Express World!" 메시지가 화면에 나타날 겁니다.

5. 라우팅(Routing) 기초: API 엔드포인트 만들기

API 서버는 다양한 *엔드포인트(Endpoint)*를 가집니다. 예를 들어 /users는 사용자 정보를 다루는 엔드포인트가 될 수 있습니다. Express에서는 app.METHOD(PATH, HANDLER) 형태로 간단하게 라우팅을 설정할 수 있습니다.

index.js 파일에 다음 코드를 추가해 봅시다.

// ... 기존 코드 아래에 추가 ...

// 임시 사용자 데이터
const users = [
  { id: 1, name: 'nova99' },
  { id: 2, name: 'techie42' },
  { id: 3, name: 'lunarcat7' }
];

// GET /api/users - 모든 사용자 목록을 반환
app.get('/api/users', (req, res) => {
  res.json(users);
});

// GET /api/users/:id - 특정 ID의 사용자를 반환
app.get('/api/users/:id', (req, res) => {
  const userId = parseInt(req.params.id);
  const user = users.find(u => u.id === userId);

  if (user) {
    res.json(user);
  } else {
    res.status(404).send('User not found');
  }
});

서버를 재시작(Ctrl + C로 종료 후 node index.js 다시 실행)하고, 브라우저에서 http://localhost:3000/api/users와 http://localhost:3000/api/users/2로 접속해 보세요. JSON 형태로 데이터가 멋지게 출력되는 것을 확인할 수 있습니다. :id와 같이 콜론으로 시작하는 부분은 **경로 매개변수(Route Parameter)**로, req.params 객체를 통해 해당 값을 가져올 수 있습니다.

6. POST 요청 처리하기: 데이터 추가

데이터를 조회하는 GET 요청을 만들었으니, 이번엔 새로운 데이터를 추가하는 POST 요청을 처리해 보겠습니다. POST 요청의 본문(body)에 담겨 오는 JSON 데이터를 파싱하기 위해서는 Express에 내장된 미들웨어를 사용해야 합니다.

index.js 상단에 다음 코드를 추가하세요.

// ... const port = 3000; 아래에 추가 ...

// JSON 요청 본문을 파싱하기 위한 미들웨어
app.use(express.json());

이제 POST 라우터를 추가합니다.

// ... 기존 라우터 아래에 추가 ...

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

  if (!newUser.name) {
    return res.status(400).send('Name is required');
  }

  users.push(newUser);
  res.status(201).json(newUser);
});

브라우저로는 POST 요청을 보내기 어려우니, Postman이나 VS Code의 Thunder Client 같은 API 테스트 도구를 사용해 보세요. http://localhost:3000/api/users 주소로 POST 요청을 보내고, Body 탭에서 raw, JSON을 선택한 뒤 {"name": "pixelwave88"}와 같은 데이터를 보내면 새로운 사용자가 추가되는 것을 확인할 수 있습니다.

7. 마무리하며

축하합니다! 여러분은 방금 Express.js를 사용하여 기본적인 REST API 서버를 구축했습니다. 오늘 배운 내용은 Express의 강력한 기능 중 아주 작은 부분에 불과합니다. 앞으로 데이터베이스 연동, 사용자 인증, 에러 핸들링, 라우트 모듈화 등 더 많은 것을 배우게 될 것입니다.

이 글이 여러분의 백엔드 개발 여정에 즐거운 첫걸음이 되었기를 바랍니다. 꾸준히 탐구하고 만들어보면서 실력을 키워나가세요! 다음 아티클에서는 오늘 만든 API를 데이터베이스와 연동하는 방법에 대해 다뤄보겠습니다.