Fielding이 말하는 진짜 REST API

REST API를 만든 장본인 Fielding은 2008년에 REST APIs must be hypertext-driven 라는 글을 작성했다. 해당 글의 내용을 보면 Fielding이 설계한 REST API는 다음의 규칙을 따라야한다.

1. 자원의 식별자와 접근 방법은 구분되어야 한다.
2. 표준 프로토콜을 있는 그대로 써라.
3. API 문서에 URL 목록을 나열하지 마라. 대신, 응답 형태를 잘 정의해라.
4. 고정된 자원 이름, 계층 구조를 사용하지마라.
5. 타입이 지정된 자원을 가지지 마라.
6. 사전 지식없이 진입할 수 있게 하라.

이러한 규칙을 따르지 않을거면 REST API라 부르지도 말고, 다른 유행어를 골라 쓰라는 말까지 할 정도로 REST API의 핵심이라고 강조하고 있다. 도대체 어떤 내용이길래 Fielding이 이렇게까지 화가 났는지 좀 더 자세히 알아보자.
 

Fielding의 REST API

1. 자원의 식별자와 접근 방법은 구분되어야 한다.

우리는 보통 서버의 REST API를 설계할 때 다음과 같이 HTTP 메소드와 자원에 해당하는 URL을 공통적으로 정의하여 접근 경로를 열어두고 있다.

GET /orders/{id}

 
하지만, Fielding은 이렇게 하지 말라고 말한다. 자원을 식별하는 것과 접근하는 방법을 구분하라고 한다. 즉, /orders/{id}와 HTTP라는 접근 프로토콜을 구분하라는 것이다. 왜냐하면 자원을 식별하는 경로는 하나지만 접근하는 프로토콜은 여러가지 일 수 있고, 같은 자원이라도 Accept 헤더에 따라 JSON, XML, HTML 등 다른 형태로 표현될 수 있기 때문이다.

http://api.example.com/orders/42
https://api.example.com/orders/42
ftp://api.example.com/orders/42

 

2. 표준 프로토콜을 있는 그대로 써라.

어떤 API를 만들때 표준 프로토콜을 변형해서 사용하는 경우는 없어야 한다는 이야기이다. 예를 들어 주문을 취소하는 API를 설계하려고 하는데, 다음과 같이 설계를 했다고 하자.

POST /orders/{id}
Custom-Action: CANCEL

 
이건 서버에서 HTTP 헤더에 커스텀 헤더를 지정하여 CANCEL이라는 행동을 나타낸다. 이는 표준 프로토콜이 아닌 본인만의 프로토콜을 추가한 꼴이 되므로 이를 이해한 서버와 클라이언트만 통신을 할 수 있게 된다. 그래서 이렇게 설계하지 말고 아래와 같이 표준을 사용하라는 것이다.

DELETE /orders/{id}

 

3. API 문서에 URL 목록을 나열하지 마라. 대신, 응답 형태를 잘 정의해라.

 
보통 이렇게 API 문서를 제공하는 방식으로 서버-클라이언트 간에 어떤 방식으로 상호작용 해야하는지 알려 주었을 것이다. 하지만, Fielding은 API 문서에 목록을 사용하는 대신에 응답이 어떻게 생겼는지를 정의하는데 노력을 쏟으라고 한다.

{
  "orderId": 42,
  "status": "PAID",
  "links": [
    { "rel": "cancel", "href": "/orders/42", "method": "DELETE" },
    { "rel": "refund", "href": "/orders/42/refund", "method": "POST" }
  ]
}

 
이렇게 응답 자체에 다음 행동으로 무엇을 할 수 있는지를 정의하여 클라이언트가 문서 없이도 응답만으로 다음 행동을 결정할 수 있도록 하라는 것이다.
 

4. 고정된 자원 이름, 계층 구조를 사용하지마라.

우리는 보통 서버에서 어떤 API를 만들고, 클라이언트는 이 API의 URL을 하드코딩하여 상호작용하도록 만든다.

restTemplate.getForObject("/api/v2/orders/42/items", Item.class);

 
하지만, 여기서 서버가 접근 경로를 /api/v3/orders/42/items로 변경한다면 클라이언트도 이에 영향을 받을 수 밖에 없다. 그래서 클라이언트가 고정된 자원 이름과 계층에 결합되지 않도록 설계를 하라는 것이다. 그러면 아래와 같은 형식으로 응답 구조를 설계할 수 있다.

{
  "orderId": 42,
  "links": [
    { "rel": "items", "href": "/api/v2/orders/42/items" }
  ]
}

 
이렇게 되면 클라이언트는 "rel"에 해당하는 items만 참조하면 다음 접근 경로를 찾을 수 있고, 이는 서버가 접근 경로를 변경해도 rel이 바뀌지 않는 이상 클라이언트에게 영향을 주지 않는다.
 

5. 타입이 지정된 자원을 가지지 마라.

보통 요청/응답의 과정에서 우리는 어떤 타입으로 변환해야 할지 이미 알고있기 때문에 응답값을 받을 때 다음과 같이 타입을 미리 지정해서 역직렬화 할 수 있도록 한다.

Order order = restTemplate.getForObject("/orders/42", Order.class);

 
하지만, Fielding은 이렇게 타입을 지정하면 서버의 도메인 모델에 의존하게 되고 서버의 변경이 곧 클라이언트의 변경으로 이어진다는걸 강조한다. 그래서 다음과 같이 타입의 분리를 하라고 말한다.

public class Resource {
    private Map<String, Object> data;
    private List<Link> links;
}

Resource resource = restTemplate.getForObject(someLink, Resource.class);

 
예시로 Resource라는 타입을 정의하고 여기에는 어떠한 의존 객체도 없이 단순히 데이터와 어떤 링크만 존재한다고 생각하는 것이다. 그러면 서버에서 구조를 변경해도 Resource에서 변경되는 지점이 없기 때문에 클라이언트에게 영향을 끼치지 않는다.
 
다만 이 방식에도 한계가 있다. 클라이언트는 결국 data.get("orderId") 처럼 키 이름에 대한 사전 지식이 필요하다. Fielding은 이를 Self-descriptive messages(자기 서술적 메시지)로 해결하려 했다.
 
응답의 Content-Type에 application/vnd.example.order+json 같은 커스텀 미디어 타입을 명시하여, "이 응답은 이런 명세를 따른다"를 응답 자체가 설명하게 만드는 것이다. application/json이 RFC 8259라는 표준 문서에 "JSON은 이런 형태다"라고 정의되어 있듯이, application/vnd.example.order+json도 "이 미디어 타입의 응답은 orderId, status 같은 필드를 포함한다"는 명세를 만들어서 공개해야 한다.
 

6. 사전 지식없이 진입할 수 있게 하라.

마지막 규칙은 지금까지 나온 내용들을 모두 종합한 것이다. 우리가 흔히 하는 방식처럼 API 문서와 같은걸 제공하지 않아도 단 한번의 루트 URL 접근으로 모든 자원의 접근 경로를 각 경로마다의 응답으로 파악할 수 있어야 한다는 뜻이다.
 
즉, 클라이언트가 `https://api.example.com`와 같은 경로로 접근하면 이후의 모든 경로는 응답에 포함된 links에서 찾아 나머지를 접근하도록 하는 것이다.
 

정리

지금까지 REST API 아버지 Fielding이 주장한 진짜 REST API에 대해서 살펴보았다. 주장하는 규칙들을 보다보면 한 가지 공통적인 특징을 발견할 수 있는데, 바로 추상화이다.
 
객체지향에서 변경에 취약한 부분을 추상화의 대상으로 보듯이, Fielding은 서버에서 변경에 취약한 부분들인 구체적인 URL 구조, 도메인 타입, 프로토콜에 의존하지 말고 응답이 제공하는 링크라는 추상화에 의존하라고 말하고 있다.
 

현대의 REST API

현실과의 괴리

지금까지의 REST API 규칙을 보면, 현재 보편적으로 말하고 구현하고 있는 REST API와 거리가 멀다는 것을 느꼈을 것이다. 대부분의 서버는 API 문서를 제공하고 있고, 클라이언트는 이러한 자원 접근 경로 및 계층을 하드코딩해서 요청/응답의 과정을 거치고있다.
 
그렇다면 우리는 잘못된 REST API를 사용하고 있는 것일까? Fielding의 규칙에 따르면 그렇다. 우리는 REST API를 사용하지 않는 것이다.
 
하지만 현실에서 그 규칙을 다 지키지 않는 데는 이유가 있다.
 

왜 지키지 않을까?

기존의 설계 방식도 충분히 REST API의 조건을 일부 만족하고 있지만, 이론적인 REST를 모두 지키기 위해서는 결론적으로는 HATEOAS를 지켜 개발해야 한다.
 

HATEOAS

HATEOAS는 Hypermedia As The Engine Of Application State의 약자로 위에서 설명했던 3, 4, 6번을 모두 포함하는 개념이다. 즉, 리소스에 대한 현재 상태와 함께 리소스가 전이될 수 있는 상태를 포함하는 것이다.
 
아까 예제로 들었던 응답을 다시보면 무슨 말인지 감이 올 것이다.

{
  "orderId": 42,
  "status": "PAID",
  "links": [
    { "rel": "cancel", "href": "/orders/42", "method": "DELETE" },
    { "rel": "refund", "href": "/orders/42/refund", "method": "POST" }
  ]
}

 
여기서 보면 현재, orderId가 42인 주문에 대한 상태가 "PAID"임을 정의하고 있고 다음으로 전이 가능한 상태로는 links에 포함된 cancel, refund가 있는 것을 알 수 있다. 이렇게 함으로써 클라이언트는 더 이상 구체적인 URL이 아닌 rel에 포함된 추상화 된 형태로 각 자원의 상태를 조작할 수 있게 된다.
 
하지만 대부분의 API는 HATEOAS까지는 구현하지 않는다. 그 이유는 다음과 같다.
 

1. 개발 비용이 크다.
   모든 응답에 "지금 상태에서 가능한 행위"를 포함시켜 응답을 만들게 되면, 서버는 매 응답마다 현재 상태에 적절한 링크를 동적으로 생성해줘야 한다. 그리고, 응답 자체의 크기도 커질 뿐더러 링크를 통해 호출해야 하는 특성상 링크를 따라가는 과정에서 불필요한 네트워크 호출 비용이 한 번 이상 발생할 수 있다.
   
   더군다나 5번 항목에서 커스텀 미디어 타입을 API마다 정의하고 명세를 관리하는 건 엄청난 비용이다.
   
   
2. 클라이언트가 활용하기 어렵다.
   아까 Resource의 예제처럼 타입이 특정되지 않는 순간 타입 안정성이 떨어진다. JACKSON 라이브러리와 같은 것을 통해 바로 사용이 가능한 객체로 변환하는 과정을 개발자가 직접 작성해야 하니 실수할 가능성이 높아진다.
   
   
3. 대부분의 서비스에서는 과잉 설계다.
   HATEOAS는 클라이언트가 누구인지 모르는 범용적인 상황에서 가치가 크다. 하지만 현실에서는 서버와 클라이언트를 같은 팀이 개발하는 경우가 많다. API 변경이 있으면 팀 내 커뮤니케이션으로 해결할 수 있는 상황에서, 모든 응답에 링크를 동적으로 생성하는 건 비용 대비 효과가 낮다.

 

마무리

Fielding의 기준에 따르면 우리는 REST API가 아니라 HTTP API를 사용하고 있는 것이다. 하지만, 이는 잘못된 선택이라기 보다는 흔히 말하듯 트레이드 오프의 과정이라고 볼 수 있을 것 같다. 공개 API처럼 클라이언트를 통제할 수 없는 환경에서는 Fielding의 원칙이 여전히 유효한 설계 지침이 될 수 있다.
 
하지만, 현실의 많은 서비스에서는 API 경로가 변경되는 빈도가 높지 않고, 서버와 클라이언트를 같은 조직이 관리하는 경우가 많다.
 
이러한 상황에서 변경의 여파를 막기 위해 HATEOAS를 도입하는건 어쩌면 오버 엔지니어링 일 수도 있다고 생각한다. 실제로 대부분의 서비스는 Open API더라도 HATEOAS를 포기하고, API 버저닝을 통해 변경의 여파를 관리하는 경우를 많이 확인할 수 있다.
 
신기한 점은 REST API도 결국 객체지향에서 중요하게 생각하는 ‘변경에 취약한 부분을 예방한다.’는 사고를 기반으로 한다는 점이다. 객체지향에서도 추상화를 트레이드 오프의 과정으로 보는만큼 REST API도 각자의 요구사항에 맞게 잘 트레이드 오프 하는 것이 중요하다고 생각한다.
 

참고

• 스프링에서도 이러한 HATEOAS를 지키면서 개발할 수 있도록 HATEOAS 라이브러리를 제공하고 있다.
• Roy Fielding의 Architectural Styles and the Design of Network-based Software Architectures, 2000 논문을 읽어보는 것도 좋을 것 같다.
• https://witch.work/en/translations/misappropriated-rest-dissertation