내가 알던 REST API와 처음 REST API는 달랐다?!

Cori1304·2025년 11월 20일

🧐 REST API가 뭐죠?

만약 개발자 면접에서 "REST API가 무엇인지 설명해 줄래요?"라고 질문하면 뭐라고 답할까? 아래와 같이 대답 할 수 있다

"REST API는 웹의 기본 프로토콜인 HTTP를 기반으로, 자원(Resource)을 이름(URI)으로 구분하고 해당 자원에 대한 행위(CRUD)를 HTTP 메서드를 통해 처리하도록 설계된 아키텍처 스타일입니다. 한마디로, 웹 상에서 데이터를 효율적으로 주고받기 위한 표준화된 통신 규약이라고 할 수 있습니다."

모범답안을 말하고 안심하겠지만, 2000년에 발표된 논문을 보면 로이 필딩(Roy Fielding)이 정의한 본래의 REST와는 거리가 있어 아쉬워할 것입니다. (REST 아키텍처 스타일 논문 작성자가 로이 필딩입니다.)

로이 필딩이 발표한 진정한 REST API가 무엇인지 자세히 살펴봅시다.

😮 REST API의 6가지 조건 (by Roy Fielding)

API가 RESTful 하다고 인정받으려면, 로이 필딩이 제시한 REST의 6가지 아키텍처 제약 조건을 만족해야 한ㄷ.

1. 클라이언트-서버 구조 (Client-Server)

규칙: 클라이언트(예: 웹 브라우저)와 서버(API 제공)가 독립적으로 분리되어야 합니다. 서버는 리소스 처리와 비즈니스 로직을, 클라이언트는 사용자 인터페이스를 담당한다.
장점: 각 부분이 독립적으로 개발 및 배포될 수 있어 상호 의존성이 낮아진다.

2. 무상태성 (Stateless)

규칙: 서버는 클라이언트의 요청 간 상태 정보(세션, 로그인 정보 등)를 저장하지 않는다. 모든 요청은 처리에 필요한 모든 정보를 스스로 포함해야 한다.
장점: 서버의 구현이 단순해지고, 수평적 확장성과 로드 밸런싱에 매우 유리

3. 캐시 처리 가능 (Cacheable)

규칙: 서버 응답은 데이터가 캐싱 가능한지 여부를 명시한다. (예: HTTP 헤더).
장점: 캐싱을 통해 불필요한 요청을 줄여 네트워크 트래픽을 감소시키고 성능을 향상시킬 수 있다.

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

규칙: 클라이언트는 서버에 직접 연결되었는지, 혹은 중간 계층(프록시, 로드 밸런서, 방화벽 등)을 통해 연결되었는지 알 필요가 없어야 한다.
장점: 시스템 보안 및 확장성을 위해 유연하게 중간 계층을 추가하고 변경할 수 있다.

5. 균일한 인터페이스 (Uniform Interface)

규칙: 시스템 전체에 걸쳐 일관되고 통일된 방식으로 상호작용이 가능해야 합니다. 이는 다음 네 가지 하위 원칙을 포함한다.
1. 리소스 식별: URI를 사용하여 자원을 명확하게 식별 가능해야 한다
2. 메시지를 통한 자원 조작: HTTP 메서드(GET, POST, PUT, DELETE)를 사용하여 자원에 대한 행위를 표현 가능해야 한다.
3. 자기 서술적 메시지: 메시지(요청/응답)만으로 그 뜻을 완전히 파악할 수 있어야 한다. (예: HTTP 헤더에 데이터 타입 명시).
4. HATEOAS: 응답에 현재 자원과 연관된 하이퍼링크를 포함하여, 클라이언트가 다음 상태로 전이하기 위해 수행할 수 있는 모든 작업을 동적으로 찾을 수 있어야 한다.
장점: API가 간결하고 예측 가능해지며, 클라이언트와 서버의 구현이 분리되어 독립적인 진화가 가능해진다.

6. Code-On-Demand (선택적 조건)

규칙: 서버가 클라이언트에게 실행 가능한 코드를 전송하여 클라이언트의 기능을 일시적으로 확장할 수 있어야 한다. (예: 자바스크립트).
참고: 이 조건은 선택 사항(Optional)이며, 필수 조건은 아닙니다.
장점: 클라이언트의 기능을 서버가 동적으로 확장할 수 있는 유연성을 제공한다.

완벽하게 REST API를 지키지 않는 이유

지금까지 개발하고 참고했던 API들을 되돌아보면, 6가지 조건을 모두 만족했는지 의문이 들었다. 그런데도 왜 사람들은 조건을 만족시키지 못했는데도 REST API라고 부르는 걸까?

1. REST는 대용량 하이퍼미디어 시스템을 위한 설계다

필딩의 논문 제목은 "네트워크 기반 소프트웨어 아키텍처의 아키텍처 스타일과 설계"이다. 즉, 특정 API 구현 방법에 대한 논문이 아니라 웹과 같은 대용량 분산 하이퍼미디어 시스템에서 사용할 아키텍처 원칙을 소개한 것이다.

현대의 REST API는 주로 데이터 교환(CRUD)에 집중하지만, 필딩의 REST는 상태 전이(HATEOAS)를 통한 시스템의 독립적 진화에 더 초점을 맞췄다는 점에서 목적과 사용처에 차이가 발생하였다.

2. HATEOAS 구현은 비효율적이다.

필딩의 REST에서 가장 중요한 원칙은 HATEOAS이다. HATEOAS를 사용하면 응답에 데이터뿐만 아니라 해당 데이터와 관련된 다음 요청에 필요한 URI를 포함하여 반환하며, 클라이언트가 서버와 동적으로 상호작용이 가능하게 한다.

<HATEOAS 예시: 상태 전이>

HATEOAS의 진정한 가치는 자원의 상태에 따라 다음 액션을 동적으로 제공하는 데 있다.

A. 주문 완료 전 상태

{
    "order_id": 500,
    "status": "PENDING",
    "total_price": 45000,
    "_links": {
        "self": { "href": "/orders/500" },
        "pay": { "href": "/orders/500/payment", "method": "POST" },
        "cancel": { "href": "/orders/500/cancel", "method": "POST" }
    }
}

클라이언트 행동: 클라이언트는 status가 PENDING일 때, 응답의 pay 또는 cancel 링크만 보고 해당 작업을 수행

B. 주문 완료 후 상태

결제를 완료하면 서버는 응답 데이터를 변경하여 pay 링크를 제거하고 refund 링크를 추가한다.

{
    "order_id": 500,
    "status": "COMPLETED",
    "total_price": 45000,
    "payment_date": "2025-11-20",
    "_links": {
        "self": { "href": "/orders/500" },
        "refund": { "href": "/orders/500/refund", "method": "POST" } 
    }
}

클라이언트 행동: 클라이언트는 이제 pay 링크가 없다는 것을 확인하고 결제 버튼을 숨기거나 비활성화하며, refund 링크를 통해 환불 요청만 할 수 있다.

하지만 현실적으로 HATEOAS를 구현하면 서버와 클라이언트 모두 개발 복잡성이 증가하여 효율성이 저하된다. 그렇기 때문에 거의 모든 상용 API는 HATEOAS를 사용하지 않는다.(필딩은 이를 HTTP API로 불러주길 원한다....)

3. SOAP의 대안과 HTTP의 편리성

2000년대 초반에는 XML 기반의 SOAP를 사용하는 API가 주를 이루었으나, SOAP는 XML 사용으로 인한 오버헤드와 복잡성이 존재했습니다. 이때, HTTP라는 이미 널리 사용되는 간단한 프로토콜을 활용하는 RESTful 방식이 편리한 대안으로 부상했습니다.

개발자들이 REST의 핵심인 'URI로 자원 식별'과 'HTTP 메서드로 행위 표현'이라는 가장 쉽고 강력한 두 가지 원칙만 차용하고, 복잡한 HATEOAS를 생략했습니다. 즉, 편의성과 실용주의 덕분에 HTTP 통신이 필요한 곳에 무분별하게 사용되며, 'REST API'라는 용어가 대중화 및 일반화된 것입니다.

4. 이미 관념이 잡혔다.

4번은 3번에 연장선이다. REST API라고 생각했던 (HTTP API)라는 이름을 바꿀 수 없게 되었다. 이미 문서와 글 그리고 회의때도 사용했고 의미 전달이 되기 때문이다. 예를 들어서 "옥동자"를 가지고 설명하면 원래는 옥(玉)같이 예쁜 어린 아들, 몹시 소중한 아들 이라는 뜻이지만, 개그맨 1명에 등장으로 의미가 별질되었다.

결론

현제 REST API는 필딩 아저씨의 API와는 다른 것이다. 목적은 같을 수 있지만 다르다. 테세우스의 배와 같다고 생각이 든다. 누구의 관점을 볼 것인가. 참 재미있는거 같다. 그래도 빌딩 아저씨 덕분에 REST API를 사용할 수 있다는 것은 맞다고 생각을 하기에 고맙다라는 마음이 든다. SOAP는 좀..