RESTful API(Representational State Transfer API)

REST는 2000년 로이 필딩(Roy Fielding)이 그의 박사 논문에서 처음 제시한 소프트웨어 아키텍처 스타일이다.
필딩은 HTTP의 주요 설계자 중 한 명으로, 웹의 기본 아키텍처를 정의하는 과정에서 REST 원칙을 발전시켰다.

REST는 네트워크 시스템, 특히 웹에서 자원을 정의하고 접근하는 방법을 제공한다. 그 이름에서 알 수 있듯이 핵심은 “표현(Representation)“과 “상태 전이(State Transfer)“이다.

RESTful API는 웹의 기본 아키텍처를 활용하여 분산 시스템에서 자원에 접근하고 조작하는 일관된 방법을 제공한다.
제약 조건을 준수할수록 확장성, 유연성, 독립성이 향상되지만, 모든 상황에 완벽한 솔루션은 아니다.

REST 원칙을 이해하고, 적절한 상황에 적용하며, 필요할 때 다른 API 스타일(GraphQL, gRPC 등)과 함께 사용하는 것이 중요하다. 이러한 지식을 바탕으로 효율적이고 확장 가능한 웹 서비스를 설계하고 구현할 수 있을 것이다.

REST의 6가지 제약 조건

REST API를 진정한 의미에서 “RESTful"하게 만들기 위해서는 다음 6가지 제약 조건을 준수해야 한다:

  1. 클라이언트-서버 아키텍처(Client-Server Architecture)

    • 사용자 인터페이스와 데이터 저장을 분리해야 한다.
    • 이를 통해 클라이언트와 서버는 독립적으로 진화할 수 있다.

  2. 무상태성(Statelessness)

    • 각 요청에는 그 요청을 이해하는 데 필요한 모든 정보가 포함되어야 한다.
    • 서버는 클라이언트의 세션 상태를 저장하지 않는다.
    • 모든 상태 정보는 클라이언트가 관리한다.

  3. 캐시 가능성(Cacheability)

    • 응답은 캐싱 가능 여부를 명시해야 한다.
    • 효율적인 캐싱은 일부 클라이언트-서버 상호작용을 제거하여 성능을 향상시킨다.

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

    • 클라이언트는 일반적으로 서버에 직접 연결되는지 중간 서버에 연결되는지 알 수 없다.
    • 중간 계층(로드 밸런서, 프록시, 게이트웨이 등)은 확장성을 향상시키고 보안 정책을 적용할 수 있다.

  5. 통일된 인터페이스(Uniform Interface)

    • REST API의 가장 중요한 특징으로, 다음 네 가지 원칙으로 구성된다:
      • 자원 식별(Resource Identification): URI를 통해 자원을 고유하게 식별한다.
      • 표현을 통한 자원 조작(Manipulation of Resources Through Representations): 클라이언트가 자원의 표현을 가지고 있다면, 서버상의 해당 자원을 수정할 권한이 있어야 한다.
      • 자기 서술적 메시지(Self-descriptive Messages): 각 메시지는 자신을 어떻게 처리해야 하는지에 대한 정보를 포함해야 한다.
      • 애플리케이션 상태 엔진으로서의 하이퍼미디어(HATEOAS): 클라이언트는 초기 URI 외에는 하드코딩된 URI를 사용하지 않고, 서버가 제공하는 링크를 통해 애플리케이션 내에서 상태 전이를 할 수 있어야 한다.

  6. 코드 온 디맨드(Code on Demand, 선택적)

    • 서버가 클라이언트에 실행 가능한 코드를 전송하여 기능을 확장할 수 있다.
    • 이는 유일한 선택적 제약 조건이다(예: JavaScript).

자원(Resources)과 URI 설계

RESTful API에서 가장 기본적인 개념은 “자원(Resource)“이다.
자원은 명사로 표현되며, URI를 통해 식별된다.

자원의 특성

URI 설계 원칙

HTTP 메서드와 CRUD 연산

RESTful API는 HTTP 메서드를 사용하여 자원에 대한 CRUD(Create, Read, Update, Delete) 연산을 수행한다.

주요 HTTP 메서드

기타 HTTP 메서드

HTTP 상태 코드

RESTful API는 표준 HTTP 상태 코드를 사용하여 요청의 결과를 나타낸다.
상태 코드는 클라이언트가 요청의 성공 여부와 다음 조치를 이해하는 데 중요하다.

주요 HTTP 상태 코드 범주

자주 사용되는 상태 코드

미디어 타입과 콘텐츠 협상

RESTful API에서는 다양한 형식으로 자원을 표현할 수 있으며, 클라이언트와 서버 간의 ‘콘텐츠 협상(Content Negotiation)‘을 통해 가장 적합한 표현을 선택한다.

주요 미디어 타입

콘텐츠 협상 방법

하이퍼미디어와 HATEOAS

HATEOAS(Hypermedia as the Engine of Application State)는 REST의 성숙도 모델에서 가장 높은 수준으로, 클라이언트가 API를 탐색할 수 있는 링크를 제공한다.

HATEOAS의 핵심 개념

HATEOAS 예시 (JSON 형식)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "_links": {
    "self": { "href": "/users/123" },
    "orders": { "href": "/users/123/orders" },
    "update": { "href": "/users/123", "method": "PUT" },
    "delete": { "href": "/users/123", "method": "DELETE" }
  }
}

보안

RESTful API의 보안은 여러 계층에서 구현될 수 있다.

인증(Authentication) 방법

권한 부여(Authorization)

기타 보안 고려사항

API 버전 관리

API가 진화함에 따라 기존 클라이언트의 호환성을 유지하면서 새로운 기능을 추가할 수 있는 버전 관리가 중요하다.

버전 관리 접근법

각 방식에는 장단점이 있으므로, 프로젝트 요구사항에 가장 적합한 방식을 선택해야 한다.

문서화

좋은 API 문서는 개발자가 API를 효과적으로 사용하는 데 필수적이다.

API 문서화 도구

문서화 모범 사례

REST 성숙도 모델(Richardson Maturity Model)

레오나르드 리처드슨(Leonard Richardson)이 제안한 REST API의 성숙도 모델은 4단계로 구성된다:

레벨 0: HTTP를 전송 메커니즘으로만 사용

레벨 1: 자원(Resources)

레벨 2: HTTP 동사

레벨 3: 하이퍼미디어 제어(HATEOAS)

많은 현대 API는 레벨 2에 해당하며, 레벨 3(HATEOAS)는 완전한 RESTful API를 위한 요구사항이지만 실제로 구현하기 어려운 경우가 많다.

REST API 설계 모범 사례

  1. 자원 식별과 URI 디자인

    • 명사 기반 자원 표현을 사용한다.
    • 일관된 복수형 명명 규칙을 유지한다.
    • 계층적 관계를 URI에 반영한다.

  2. 메서드 사용

    • HTTP 메서드의 의미에 맞게 API를 설계한다.
    • 멱등성과 안전성을 고려한다.
    • 특수 작업은 하위 자원으로 모델링한다(예: /users/123/activate).

  3. 상태 코드

    • 표준 HTTP 상태 코드를 사용한다.
    • 오류 응답에 의미 있는 메시지를 포함한다.

  4. 페이지네이션, 필터링, 정렬

    • 컬렉션 자원에 페이지네이션을 구현한다(예: ?page=2&size=10).
    • 필터링을 위한 쿼리 파라미터를 제공한다(예: ?status=active).
    • 정렬을 위한 파라미터를 지원한다(예: ?sort=name,asc).

  5. 응답 형식

    • 일관된 응답 구조를 유지한다.
    • 필요한 메타데이터를 포함한다.
    • 오류 응답을 표준화한다.

  6. 성능 최적화

    • 적절한 캐싱 헤더를 사용한다.
    • 필요한 데이터만 반환하도록 최적화한다.
    • 압축(gzip, deflate)을 사용한다.

REST API와 다른 API 스타일 비교

REST vs. SOAP

REST vs. GraphQL

REST vs. gRPC

RESTful API의 한계

REST가 많은 장점을 제공하지만, 몇 가지 한계와 도전 과제도 있다:

  1. 오버페칭과 언더페칭

    • 클라이언트가 필요한 데이터보다 많거나 적은 데이터를 받을 수 있다.
    • 여러 관련 자원을 조회하려면 여러 API 호출이 필요할 수 있다.

  2. 문서화 표준 부족

    • REST 자체는 API 문서화를 위한 표준 방식을 정의하지 않는다.
    • OpenAPI와 같은 도구가 이 문제를 해결하기 위해 등장했다.

  3. 복잡한 트랜잭션

    • 여러 자원에 걸친 트랜잭션 처리는 REST에서 자연스럽게 지원되지 않는다.

  4. HATEOAS 구현의 어려움

    • 완전한 HATEOAS 구현은 복잡하고 많은 오버헤드를 발생시킬 수 있다.

용어 정리

용어설명

참고 및 출처

RESTful API: Principles, Design, and Best Practices | Leapcell