RESTful API(Representational State Transfer API)

•

2025년 04월 04일 발행•2025년 04월 04일 수정

요약

REST(Representational State Transfer) 아키텍처 스타일을 따르는 웹 API

초급

기본적인 HTTP 개념과 URI 설계 원칙, JSON 구조 이해가 필요하다

태그

API 모델 서빙

#개념

RESTful API는 웹에서 자원을 효율적으로 다루기 위한 아키텍처 스타일로, 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하는 인터페이스 설계 방식이다. 여기서 REST란 Representational State Transfer의 줄임말로, 자원(resource)을 URI로 식별하고 HTTP 메서드를 통해 자원에 대한 상태를 전송하는 웹 아키텍처 스타일을 말한다. 명령어 중심이 아니라 URI와 메서드만으로 동작을 명확하게 구분할 수 있어, 시스템 간의 데이터 통신을 단순하고 예측 가능하게 만들어준다.

이론적으로는 다른 프로토콜 위에서도 REST 원칙을 구현할 수 있지만, 실제로는 거의 모든 RESTful API가 HTTP를 기반으로 구현된다. 이는 REST가 2000년 로이 필딩(Roy Fielding)의 박사 학위 논문에서 HTTP와 웹 아키텍처의 설계 원리를 정리하는 과정에서 정의되었고, HTTP의 특성을 그대로 활용하는 것을 목표로 하기 때문이다. RESTful API의 설계원칙은 다음과 같다.

API 설계 원칙

일관된 인터페이스: URI로 지정한 자원에 대한 조작을 통일되고 한정적인 인터페이스로 수행한다.
클라이언트-서버 구조: 클라이언트와 서버의 역할을 분리한다.
무상태: 각 요청은 처리에 필요한 정보를 스스로 포함하며, 서버는 클라이언트의 세션 상태를 저장하지 않는다.
계층형 구조: 보안, 로드밸런싱, 캐싱 등을 위한 계층을 추가할 수 있다.
캐시 가능: HTTP의 캐시 기능을 활용한다.

RESTful API의 주요 특징 중 하나는 HTTP 메서드(GET, POST, PUT, PATCH, DELETE 등)를 의미에 맞게 일관성 있게 활용한다는 것이다. 예를 들어 블로그 서비스에서 게시글을 다루는 기능을 RESTful하게 설계한다고 가정해보자. /posts는 게시글 목록이라는 자원을 의미하며, GET /posts는 글 목록을 조회하고, POST /posts는 새로운 글을 생성하는 요청이다.

또한 RESTful API는 무상태(stateless)성을 가지는데, 이는 각각의 요청이 독립적으로 처리되며, 서버는 이전 요청의 상태를 기억하지 않는다는 뜻이다. 이러한 구조는 시스템이 확장되고 분산되는 환경에서 특히 유리하다.

또 다른 특징으로는 URI를 동사 대신 명사를 중심으로 구성하며, 계층적인 자원 구조를 표현해야한다는 것이 있다. 예를 들어 /users/123/orders는 사용자 123의 주문 목록을 의미하는 URI이다. 또한 서버는 클라이언트에게 의미 있는 응답을 제공하기 위해 HTTP 상태 코드를 적절히 사용해야 한다. 예를 들어, 요청이 성공했을 때는 200 OK, 잘못된 요청일 경우 400 Bad Request를 반환한다.

한편, RESTful API에는 몇 가지 단점이나 한계도 존재한다. 대표적인 문제로 과대요청과 과소요청이 있다. 과대요청(over-fetching)이란 클라이언트가 필요한 이상으로 불필요한 데이터까지 한꺼번에 전달받는 상황을 뜻한다. 예를 들어 어떤 API 엔드포인트가 직원 정보 전체를 반환하도록 고정되어 있을 때, 클라이언트는 단지 직원 이름만 필요하더라도 직책, 생년월일 등의 불필요한 정보까지 수신하게 될 수 있다.

반대로 과소요청(under-fetching)은 한 번의 요청으로 필요한 데이터를 모두 얻지 못해 여러 번 나누어 요청해야 하는 상황을 말한다. 예를 들어 게시글 목록을 얻은 뒤 각 게시글의 세부 정보를 가져오기 위해 추가 API 호출을 $n$번 해야 한다면, 이는 데이터 획득을 위해 $n+1$개의 요청이 필요한 비효율적인 패턴을 초래한다. 이러한 문제는 RESTful API의 리소스 단위 응답이 정해진 구조로 고정되어 발생하는 한계로 지적되며, 특히 모바일 환경처럼 네트워크가 제한적인 경우 성능 저하로 이어질 수 있다.

실무에서 RESTful API는 데이터 분야의 다양한 시나리오에 활용된다. 머신러닝 모델을 RESTful API로 서빙하면 다른 시스템이 HTTP 요청만으로 예측 결과를 쉽게 받을 수 있다. 예를 들어, 데이터 사이언티스트가 개발한 주택 가격 예측 모델에 /predict-house-price같은 엔드포인트로 JSON 형식의 입력 데이터를 전송하고, 예측 결과를 JSON으로 응답받을 수 있다. 실제로 Flask, Django 같은 파이썬 웹 프레임워크나 TensorFlow Serving, AWS SageMaker 등 머신러닝 서빙 플랫폼은 RESTful API 형태로 모델 예측 기능을 노출하는 기능을 제공한다.

또한 데이터 수집 파이프라인에서도 RESTful API는 핵심 역할을 한다. IoT 센서나 외부 API로부터 데이터를 받아와 내부 시스템으로 전달하고, 가공 및 저장하는 흐름을 구성할 수 있다. RESTful API를 사용하면 시스템 간 의존도를 줄이면서 모듈화된 구조를 만들 수 있으며, 마이크로서비스 간 통신, Webhook 이벤트 처리 등에서도 폭넓게 활용된다. 데이터 플랫폼 설계 시 RESTful API를 활용하면 유연성과 확장성을 동시에 확보할 수 있다.