RESTful API 설계의 핵심 원칙

RESTful API란 무엇인가

RESTful API는 **Representational State Transfer(표현 상태 전달)**라는 아키텍처 스타일을 따르는 웹 API 설계 방식이다.
주로 HTTP 프로토콜을 기반으로 하며, **자원(Resource)**을 중심으로 데이터를 주고받는다.

단순한 데이터 전송이 아닌, 명확한 설계 원칙과 구조를 갖춘 통신 방식이다.

 

RESTful API의 핵심 개념

REST의 철학은 다음과 같다:

• 자원의 표현(Representation)을 전송(Transfer) 하여, 클라이언트와 서버가 상태를 주고받는다.
• 서버는 상태를 저장하지 않는 Stateless 구조를 따른다.
• HTTP URI로 자원을 식별하고, HTTP 메서드를 통해 행위를 정의한다.

이러한 원칙을 따르는 API를 RESTful API라고 부른다.

---

RESTful API의 6가지 핵심 원칙

1. 자원 지향 아키텍처

REST API는 모든 것을 자원(Resource) 중심으로 설계한다. 각 자원은 고유한 URI(Uniform Resource Identifier) 로 식별되며, URL을 통해 자원의 위치를 명확히 표현해야 한다.

 

• • URL 설계 규칙
    • 명사 사용 및 복수형 표현
      • 자원 이름은 명사로 표현하고, 복수형을 사용한다.
      • 예시:
        /users → 사용자 목록
        /products → 상품 목록
        /orders → 주문 목록
    • HTTP 메서드로 행위 구분 (CRUD 매핑)
      • GET /users → 사용자 목록 조회
      • POST /users → 사용자 생성
      • GET /users/{id} → 특정 사용자 조회
      • PUT /users/{id} → 사용자 정보 수정
      • DELETE /users/{id} → 사용자 삭제
    • 경로 변수 최소화 및 계층 구조 표현
      • 필요한 최소한의 경로 변수만 사용
      • 계층적 관계는 URL로 표현
      • 예시:
        /users/{userId}/orders → 특정 사용자의 주문 목록 조회
    • 쿼리 매개변수로 필터링, 정렬, 페이징 지원
      • 예시:
        /products?category=electronics&sort=price&page=2&size=10
    • 버전 관리 필수
      • API의 안정성을 위해 버전을 URI에 명시
      • 예시:
        /api/v1/users

 

2. 무상태성 (Stateless)

서버는 클라이언트의 상태 정보를 저장하지 않는다.
각 요청은 완전 독립적으로 동작하며, 필요한 모든 정보는 요청에 포함되어야 한다.

장점:

• 서버 확장성 향상
• 요청 간 간섭 최소화
• 시스템 복잡도 감소

3. 캐시 가능 (Cacheable)

캐시 사용은 네트워크 지연을 줄이고, 서버의 부하를 경감시키며, 전반적인 성능을 향상시킨다. 따라서 API 응답에는 캐싱 정책을 명시해야 하고, 클라이언트가 응답을 적절히 캐시할 수 있도록 해야한다.

 

4. 클라이언트 - 서버 구조 분리

REST는 클라이언트와 서버가 독립적으로 동작할 수 있도록 분리된 구조를 강조한다.

각 부분의 독립적인 진화를 가능하게 하여, 서버의 기능 개선이 클라이언트의 업데이트 없이 이루어질 수 있도록 지원한다.

 

5. 계층화 시스템 (Layered System)

클라이언트는 요청이 직접 서버에 도달하는지, 중간에 프록시나 게이트웨이가 있는지 알 수 없다.
이 계층 구조 덕분에 로드 밸런싱, 보안, 암호화 등을 투명하게 적용할 수 있다.

 

6. 코드 온 디맨드 (선택 사항)

서버가 실행 가능한 코드를 클라이언트에 전송하여 클라이언트의 기능을 일시적으로 확장할 수 있음을 의미한다. 이 원칙은 클라이언트의 유연성을 높이지만, 필수는 아니다.

 

---