RESTful API란?

REST(Representational State Transfer)는 웹의 장점을 최대한 활용할 수 있는 아키텍처로, 2000년 로이 필딩이 제안했습니다.
RESTful API는 이 REST 아키텍처의 제약 조건과 설계 원칙을 준수하는 API를 의미합니다.
이번 글 에서는 설계 원칙을 위주로 다루어 볼 예정입니다.

RESTful API의 핵심 설계 원칙

1. 리소스 중심의 URL 설계

• URL Path에는 동작이아닌 리소스의 위치와 계층 관계만을 나타내도록 합니다.
• 리소스에 가해질 행동(Operation)은 HTTP Method를 세멘틱 하게 사용하여 표현 합니다. (아래에 자세하게 설명.)

# RESTful하지 않은 기존 API 설계
GET /getUser/123
POST /createOrder
PUT /updateProduct/456
DELETE /deletePayment/789

# RESTful API 설계
GET /users/123
POST /orders
PUT /products/456
DELETE /payments/789

RESTful API 설계의 장점:

• URL만으로도 어떤 리소스에 접근하는지 직관적으로 이해 가능
• 일관된 URL 구조로 예측 가능성이 높음
• 리소스의 계층 구조를 URL에 자연스럽게 반영 가능 (예: /users/123/orders)

2. HTTP 메서드의 의미적 사용

각 HTTP 메서드는 명확한 의미를 가지고 사용됩니다:

• GET: 리소스 조회
• POST: 새로운 리소스 생성
• PUT: 리소스 전체 수정
• PATCH: 리소스 부분 수정
• DELETE: 리소스 삭제

장점:

• 동작의 의미가 HTTP 메서드에 이미 담겨있어 URL이 단순해짐
• CRUD 작업을 일관된 방식으로 처리 가능
• 캐싱, 보안 정책 등을 HTTP 표준에 따라 쉽게 적용 가능

3. 상태를 가지지 않는 통신 (Stateless)

모든 요청은 이전 요청과 독립적으로 필요한 모든 정보를 포함해야 합니다.

장점:

• 서버 확장이 용이
• 요청의 독립적인 처리가 가능
• 시스템 복잡도 감소

실제 적용 예시

회원과 주문 관리 API 예시:

# 회원 관리
GET /users           # 회원 목록 조회
GET /users/123       # 특정 회원 조회
POST /users          # 새 회원 등록
PUT /users/123       # 회원 정보 수정

# 주문 관리
GET /users/123/orders      # 특정 회원의 주문 목록
POST /orders              # 새 주문 생성
GET /orders/456           # 특정 주문 조회
PUT /orders/456           # 주문 정보 수정

이 구조의 장점:

• URL만으로도 리소스 간의 관계가 명확함
• API 사용법을 직관적으로 이해할 수 있음
• 시스템 확장 시 일관된 패턴으로 새로운 API 추가 가능

이렇게 RESTful한 API를 설계하면 API를 사용하는 클라이언트에게 많은 이점을 제공합니다.
하지만 과연, RESTful API는 단순히 클라이언트에게만 이점을 제공할까요?
제 생각은 '아니다, RESTful한 API를 설계할 때 서버사이드 개발자에게도 아주 많은 이점을 제공한다' 입니다.
관련 내용은 아래 제 포스팅에서 좀 더 자세히 다루었습니다.

 

2024.12.12 - [개발 경험 기록/기타] - RESTful 한 API 설계는 사실 클라이언트 뿐만 아니라 개발자에게도 많은 이점을 제공한다.

RESTful 한 API 설계는 사실 클라이언트 뿐만 아니라 개발자에게도 많은 이점을 제공한다.