REST API 란? 초보자 관점에서 시작해보는 개념 정리

REST API 란 무엇인가?

회사에서 개발을 하는데 REST API 란 용어가 자주 사용되고 있다. REST(Representational State Transfer) 란 용어는 2000년 로이 필딩(Roy Fielding)의 박사 논문에서 처음 소개된 아키텍처 스타일로 단순하고 일관성 있게 클라이언트, 서버 간 통신을 표현 한다. 그리고 이 규칙을 따라 작성된 API 가 바로 REST API다.

현대의 소프트웨어 개발에서 REST API는 필수적인 개념으로 자리 잡았다. 특히, 웹 애플리케이션, 모바일 앱, 클라우드 서비스 등 다양한 분야에서 시스템 간 데이터를 주고받기 위해 REST API는 표준적인 방법으로 널리 사용되고 있다. 그러나 REST API라는 용어가 주는 복잡한 느낌 때문에 나와같은 초보자들은 쉽게 이해하지 못하거나, 어디서부터 시작해야 할지 막막함을 느끼기 쉽다.

이 글에서는 REST API의 기본 개념부터 RESTful 아키텍처의 철학, 설계 원칙, 그리고 실제로 이를 활용한 간단한 사례를 통해 REST API를 깊이 파헤쳐 보기 위해 작성 되었다. 이 글을 읽고 나면 REST API가 단순한 용어가 아닌, 웹 개발의 중요한 도구임을 이해할 수 있을 것이다.

REST API의 세계로 함께 들어가 보자. 😊

REST API 의 기본 형태

REST API 는 기본적으로 HTTP 프로토콜을 활용하며 HTTP 메서드, URL 구조를 지닌다. 여기서 먼저 HTTP 메서드에 대해 알아보자.

HTTP 메서드

HTTP 메서드는 클라이언트의 요청이 무엇 인지를 구분하기 위한 구성 요소이다. 호출 하는 쪽에서 어떤 메서드를 보내냐에 따라 데이터 조회, 생성, 수정 등을 구분할 수 있다.

REST API URL

http://도메인/자원/식별자

위의 URL 은 기본적인 HTTP 프로토콜 API 이다. 이때 자원은 명사로, 식별자(예를 들어 같은 데이터 조회여도 전체 조회인지 등을 구분하기 위한 추가 요로)에 따라 동작이 달라지는 형태이다.

REST API 의 특징

1. 자원 중심의 명사 기반 URL 사용

REST API 는 자원 중심의 명사를 이용해 URL을 만드는데, 작업 중심의 URL 을 사용한다면 이는 RESTful 하지 않다. USER 정보를 가져오는 API URL 을 작성할 때, /getUserInfo 등으로 작성하지 않고 /users 도메인 하나에 메서드 방식에 동작이 달라지도록 설계한다.

과거엔 이런 RESTful API 설계 원칙이 널리 알려지지 않아 GET, POST 메서드만 사용하고 URL 에 따라 동작이 달라지게 설계 하였다. 그래서 RESTful API 를 제공 받았는데 사실 이 원칙을 지키는 경우가 없는 경우도 많았다.

따라서 REST API 를 만든다면 자원을 명확하게 식별할 수 있는 명사 URL 로 작성한다.

RESTful – ⭐

RESTful 이란 용어는 얼마나 REST 처럼 보이는 혹은 REST 원칙을 따르는 정도의 용어로 제공되는 API 가 REST 에 맞춰 제공되는가를 의미한다. RESTful API 는 얼마나 REST 원칙에 맞춰 개발된 API 인가를 이야기 한다.

2. HTTP 메서드로 작업 구분

위의 내용들과 이어지는 내용으로 URL 은 자원 중심으로 작성 된 후 HTTP 메서드로 구분된다. http://도메인/users 라는 URL 이 하나 존재하고 이를 어떤 메서드로 호출하냐에 따라 작업이 구분된다.

3. 무상태성

서버는 클라이언트의 상태를 기억하지 않아서 클라이언트는 요청 때 마다 해당 정보를 포함해서 줘야 한다. 예로 API 를 사용할 때 인증 받아야 하는 토큰 값 등이 있을 때, 한번 인증한 후에도 사용할 때마다 토큰 값을 다시 받도록 설계 해야 한다.

4. 표준 포맷의 데이터 형태

응답(response) 데이터는 JSON, XML 같은 표준 포맷으로 반환 된다.

5. 데이터 캐싱

캐싱은 자주 사용할 데이터를 일시적으로 저장해 재사용 하여 서버에 대한 부하를 줄이기 위한 기술 중 하나로 HTTP 헤더를 사용하여 캐시 서버가 데이터를 캐싱할 수 있도록 제어한다. 이 때, 데이터는 고유의 식별자(ETag)를 지녀 이 값이 변경 될 당시에 데이터를 반환 하도록 설계할 수 있다.

REST API 예제 코드 (Node.js + Express 모듈)

const express = require('express');
const app = express();
const PORT = 3000;

// Mock 데이터
const users = [
	{ id: 1, name: 'Alice', email: 'alice@example.com' },
	{ id: 2, name: 'Bob', email: 'bob@example.com' },
];

// 모든 유저 조회
app.get('/users', (req, res) => {
    res.status(200).json(users);
});

// 특정 유저 조회
app.get('/users/:id', (req, res) => {
    const userId = parseInt(req.params.id, 10);
    const user = users.find(u => u.id === userId);
    if (user) {
        res.status(200).json(user);
    } else {
        res.status(404).json({ message: 'User not found' });
    }
});

app.listen(PORT, () => {
    console.log(`Server is running on http://localhost:${PORT}`);
});

위의 코드는 Node.js 기반의 구현 코드이다. url 은 /uesrs 에 유저 조회에 대한 get 만 구현되어 있다. 만약 다른 메서드를 구현할 땐 app.post 등으로 구현이 가능하다.

위의 예제 코드로 API 서버를 구현 했다면 클라이언트에서 다음과 같은 코드 형태로 호출할 수 있다.

JavaScript 에서 Fetch API 를 사용한 호출

async function fetchAllUsers() {
    try {
        const response = await fetch('http://localhost:3000/users');
        if (!response.ok) {
            throw new Error('Error fetching users');
        }
        const data = await response.json();
        console.log('All Users:', data);
    } catch (error) {
        console.error('Error:', error.message);
    }
}

fetchAllUsers();

await fetch 영역에 URL 을 입력하면 API 가 호출 되어 위의 코드에 있는 users 안의 값이 response 에 담기고 이 안의 값은 .json(), .data() 등의 메서드로 가져올 수 있다.

이 코드 외에도 과거 Axios 모듈에 대해 다룰 때 API 관련 글을 작성한 적이 있다. (Node.js Axios 모듈: HTTP 요청으로 REST API 호출하기)

이처럼 URL 하나만 알아도 데이터를 주고 받을 수 있는 REST API 는 편리하며 자주 사용하는 API 방식이 되었다. 지금까지 이 용어를 자주 사용했음에도 정확하게 무엇을 의미하는지 알기 힘들었는데 정리함으로써 좀 더 이해가 쉽게 될 수 있어서 좋은 시간이였다.