IT용어위키

RESTful API(Representational State Transfer Application Programming Interface)는 REST 아키텍처 스타일을 따르는 웹 API로, 클라이언트와 서버 간의 통신을 간단하고 일관된 방식으로 설계한 인터페이스이다.

개요

RESTful API는 HTTP 프로토콜을 기반으로 자원을 URI(Uniform Resource Identifier)로 표현하고, HTTP 메서드(GET, POST, PUT, DELETE 등)를 통해 자원을 조작한다. REST 아키텍처는 상태 비저장(stateless), 클라이언트-서버 구조, 캐시 처리, 계층 구조 등의 제약 조건을 따르며, 이를 만족하는 API는 RESTful하다고 간주된다.

구성 요소

RESTful API는 다음과 같은 구성 요소를 기반으로 설계된다.

자원(Resource): 고유한 URI로 식별되며, 명사 형태로 표현됨 (예: `/users`, `/products`)
메서드(Method): HTTP 메서드를 사용하여 자원에 대한 동작을 정의
- GET: 자원의 조회
- POST: 자원의 생성
- PUT: 자원의 전체 수정
- PATCH: 자원의 부분 수정
- DELETE: 자원의 삭제
표현(Representation): 클라이언트와 서버는 일반적으로 JSON, XML 등의 형식으로 자원의 상태를 주고받음
상태 비저장성: 각 요청은 독립적으로 처리되며, 서버는 이전 요청 상태를 기억하지 않음

RESTful의 설계 원칙

RESTful API를 설계할 때는 다음과 같은 원칙을 지켜야 한다.

일관된 URI 설계: 자원 중심의 URI를 사용하며 동사 대신 명사를 사용
표준 HTTP 메서드 사용: 기능에 따라 적절한 메서드를 활용
상태 비저장성 유지: 서버는 클라이언트의 상태를 저장하지 않음
계층화된 시스템: 중간 서버를 통한 로드 밸런싱, 캐싱 등이 가능
캐시 처리: 응답에 캐시 가능 여부를 명시하여 성능 최적화
자체 표현(Self-descriptive) 메시지: 요청에 필요한 모든 정보가 포함됨

URI 설계 규칙

RESTful API에서 URI는 자원을 식별하기 위한 핵심 요소로, 명확하고 일관된 규칙을 따라야 한다. 다음은 대표적인 URI 설계 규칙이다.

URI는 명사를 사용하여 자원을 표현해야 하며, 동사는 사용하지 않는다.
- 예: `/getUserInfo` 대신 `/users/info`
URI는 복수형 명사를 사용한다.
- 예: `/user` 보다는 `/users`
계층 구조를 나타내는 경우 URI 경로를 계층적으로 표현한다.
- 예: `/users/42/orders/3` (사용자 42번의 주문 3번)
자원의 식별자는 URI 경로에 포함시키며, 쿼리 파라미터로 넘기지 않는다.
- 예: `/users?id=42` 대신 `/users/42`
하위 자원(Sub-resource)은 부모 자원에 종속된 경로로 표현한다.
- 예: `/users/42/posts` (사용자 42번이 작성한 게시물)
파일 확장자는 URI에 포함하지 않는다. 대신 Accept 헤더를 사용해 표현 형식을 지정한다.
- 예: `/users.json` 대신 `/users` + `Accept: application/json`
하이픈(`-`)을 단어 구분자로 사용하고, 밑줄(`_`)은 사용하지 않는다.
- 예: `/user-profile` (권장) vs `/user_profile` (비권장)
소문자를 사용한다. 대문자는 피한다.
API 버전은 URI에 명시할 수 있으나, 가능한 한 헤더 방식 버전 관리가 권장된다.
- URI 방식 예: `/v1/users`
- 헤더 방식 예: `Accept: application/vnd.example.v1+json`

장점과 단점

장점

단순하고 직관적인 URI 구조
HTTP 표준을 그대로 활용하므로 다양한 플랫폼에서 호환 가능
클라이언트와 서버의 역할 분리
확장성 및 유연성 뛰어남

단점

복잡한 트랜잭션 처리에는 적합하지 않음
상태 비저장성으로 인해 반복적인 인증 정보 전송 필요
메시지 오버헤드가 클 수 있음(JSON 등 데이터 포맷 사용)

REST와 RESTful의 차이

REST는 아키텍처 스타일 자체를 의미하며, RESTful은 이 스타일을 구현한 API를 의미한다. 즉, 모든 RESTful API는 REST의 제약 조건을 따르지만, 실질적으로 이를 완전히 준수하지 않는 경우도 많아 "REST-like" 또는 "준REST"라는 표현이 사용되기도 한다.

활용 사례

클라우드 서비스(API Gateway, AWS, GCP 등)
모바일 애플리케이션과 서버 간 통신
프론트엔드와 백엔드 간 데이터 교환
IoT 기기 제어 및 데이터 수집

같이 보기

참고 문헌

Roy T. Fielding, *Architectural Styles and the Design of Network-based Software Architectures*, University of California, Irvine, 2000.
Leonard Richardson, Sam Ruby, *RESTful Web Services*, O'Reilly Media, 2007.