목차
- RESTful API의 개념과 등장 배경
- REST 아키텍처의 핵심 구성요소
- RESTful API 설계 원칙
- RESTful API 와 다른 방식 비교
- 적용 시 참고사항
1. RESTful API의 개념과 등장 배경
REST(Representational State Transfer)는 2000년 로이 필딩(Roy Fielding)이 자신의 박사 논문에서 처음 소개한 소프트웨어 아키텍처 스타일이다. 필딩은 웹의 창시자 중 한 명으로, HTTP 프로토콜 설계에도 참여했다. 그는 웹의 장점을 최대한 활용할 수 있는 아키텍처로 REST를 제안했다.
RESTful API란 REST 아키텍처의 제약조건을 준수하는 애플리케이션 프로그래밍 인터페이스를 말한다. 쉽게 말해, 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하면서 웹 서비스를 설계하는 방법이다.
REST의 이름에서 알 수 있듯이, 이 아키텍처는 네트워크 상에서 자원의 상태가 어떻게 전송(Transfer)되는지를 표현(Representation)하는 방식에 중점을 둔다. 클라이언트가 서버에 요청을 보내면 서버는 적절한 자원의 상태(State)를 클라이언트에게 전송하는 방식으로 동작한다.
2. REST 아키텍처의 핵심 구성요소
RESTful API는 세 가지 핵심 구성요소를 통해 구현된다.
1) Resource(자원)
- 모든 자원은 고유한 URI(Uniform Resource Identifier)로 식별된다.
- 예: https://api.example.com/users/123은 ID가 123인 사용자 자원을 나타낸다.
- URI는 자원을 명확하게 표현해야 하며, 동사보다는 명사를 사용한다.
2) Method(메소드)
- HTTP 메소드를 사용하여 자원에 대한 작업을 정의한다.
- 주요 메소드
- GET: 자원 조회
- POST: 자원 생성
- PUT: 자원 전체 수정
- PATCH: 자원 일부 수정
- DELETE: 자원 삭제
3) Representation(표현)
- 클라이언트와 서버가 데이터를 주고받는 형태
- 일반적으로 JSON, XML 등의 형식을 사용
- 같은 자원이라도 다양한 형태로 표현될 수 있다(JSON, XML, HTML 등)
이 세 요소를 통해 네트워크 상태의 전이(State Transfer)를 표현함으로써 RESTful한 API를 설계할 수 있다.
3. RESTful API 설계 원칙
1) 클라이언트-서버 구조
- 클라이언트와 서버가 독립적으로 분리되어 있어야 한다.
- 이를 통해 각 파트의 독립적인 개발과 확장이 가능하다.
2) 무상태성(Stateless)
- 각 요청은 이전 요청과 독립적이며, 서버는 클라이언트의 상태를 저장하지 않는다.
- 모든 요청은 필요한 모든 정보를 포함해야 한다.
3) 캐시 가능성(Cacheable)
- 응답은 캐시 가능 여부를 명시해야 한다.
- 효율적인 캐싱은 성능 향상에 크게 기여한다.
4) 계층화 시스템(Layered System)
- 클라이언트는 서버에 직접 연결되었는지, 중간 서버를 통해 연결되었는지 알 수 없다.
- 이를 통해 로드 밸런싱, 공유 캐시 등의 기능을 추가할 수 있다.
5) 인터페이스 일관성(Uniform Interface)
- 일관된 인터페이스로 전체 시스템 아키텍처를 단순화하고 상호작용의 가시성을 향상시킨다.
- URI는 리소스를 명확하게 식별해야 하며, 리소스 조작은 HTTP 메소드를 통해 이루어져야 한다.
(참고) 예시
# 좋은 예시
GET /users # 사용자 목록 조회
GET /users/123 # 특정 사용자 조회
POST /users # 새 사용자 생성
PUT /users/123 # 사용자 정보 전체 수정
PATCH /users/123 # 사용자 정보 일부 수정
DELETE /users/123 # 사용자 삭제
# 나쁜 예시
GET /getUsers # 동사 사용
POST /users/create # 중복 의미
GET /users/123/delete # GET으로 삭제 액션
4. RESTful API 와 다른 방식 비교
1) SOAP(Simple Object Access Protocol)
- 더 엄격한 표준을 가지며, XML만 사용
- 보안, 트랜잭션 등에서 더 많은 기능 제공
- REST보다 더 많은 대역폭 사용
2) GraphQL
- 페이스북에서 개발한 쿼리 언어 및 런타임
- 클라이언트가 필요한 데이터만 정확히 요청 가능
- 여러 리소스를 하나의 요청으로 가져올 수 있음
- 오버페칭/언더페칭 문제 해결
3) gRPC
- 구글에서 개발한 고성능 RPC(Remote Procedure Call) 프레임워크
- Protocol Buffers를 사용한 바이너리 직렬화로 높은 성능
- 양방향 스트리밍 지원
- 마이크로서비스 아키텍처에 적합
RESTful API는 이해하기 쉽고, HTTP 프로토콜을 그대로 활용하며, 웹 기반 서비스에 적합하다는 장점이 있다. 특히 공개 API나 범용적인 서비스에 적합하다.
5. 적용 시 참고사항
RESTful API 설계시 다음과 같은 HTTP 상태코드나 버전 명시를 적절히 사용하는 것이 좋다.
1) HTTP 상태 코드의 적절한 활용
- 200: 성공
- 201: 리소스 생성 성공
- 400: 잘못된 요청
- 401: 인증 실패
- 403: 권한 없음
- 404: 리소스 없음
- 500: 서버 오류
2) 버전 관리
https://api.example.com/v1/users
https://api.example.com/v2/users
Accept: application/vnd.example.v1+json
RESTful API는 웹 서비스 설계의 가장 보편적인 방식 중 하나로, 자원(Resource), 메소드(Method), 표현(Representation)이라는 세 가지 핵심 요소를 기반으로 한다. 이 아키텍처 스타일은 단순성, 확장성, 독립성, 그리고 성능이라는 장점을 제공한다.
실무에서 RESTful API를 설계할 때는 URI 설계, HTTP 메소드의 적절한 사용, 상태 코드 활용, 버전 관리, 보안 등 여러 측면을 고려해야 한다. 모든 제약조건을 완벽하게 충족시키기는 어렵지만, REST의 핵심 원칙을 따르는 것만으로도 유지보수가 용이하고 직관적인 API를 구축할 수 있다.
현대 웹 개발 환경에서는 GraphQL, gRPC 등 다른 API 디자인 방식도 인기를 얻고 있지만, RESTful API는 여전히 그 단순함과 확장성으로 인해 널리 사용되고 있다. 각 프로젝트의 요구사항에 맞는 API 설계 방식을 선택하되, RESTful 원칙을 잘 이해하고 적용하는 것이 중요하다.