HATEOAS가 이루고자 하는 이상과 현실의 차이가 존재한다. 개발과 의사결정 속도가 중요한 조직에서는 쓰지 않아도 좋다.

API 디자인을 시작하면서 뭔가 정말 제대로 REST 아키텍쳐를 만들고 싶어서 마틴 파울러가 쓴 REST성숙도 모델도 읽어보고 여러가지 자료 조사를해 보았다.

하나의 엔드포인트를 여러개의 리소스에 할당하기 보다 각 리소스를 그에 맞는 엔드포인트에 맵핑하고 API의 동작은 HTTP의 method를 동사로서 사용한다. 여기까지가 레벨2,대부분의 개발자들(백엔드,클라이언트모두 포함)이 이부분은 쉽게 이해하고 따라할 수 있지만 문제는 레벨 3부터 시작되었다.

하이퍼 미디어 컨트롤, 뭔가 멋진 단어들을 많이 모아 놓았지만 이 레벨은 HATEOAS가 적용되었냐 아니냐가 그 판단 기준이다.

REST API의 창시자인 로이필딩 (Roy Fielding)은 REST API는 반드시 하이퍼 미디어 드리븐이어야 하며 그렇지 않다면 그것은 REST가 아니라 RPC라고 주장한다. , 2008년의 글이지만 논문의 원저자이기 때문에 지금까지 미치는 파장이 적지 않은 것 같다.

HATEOAS의 장점

HATEOAS 를 적용하면 얻게 되는 장점이 무었일까, 당장 생각나는 것은 애플리케이션의 리소스가 상태머신(State Machine)으로서 해석될 수 있다는 것이다. 즉 상태머신이 가지는 장점을 API인터페이스에도 그대로 적용할 수 있다. 두번째는 API와 컨슈머의 결합이 느슨해진다는 점이다.

무슨 말이냐 하면 아래와 같은 응답이 있다고 가정하자. API응답을 봐도 상품 목록에서 이동할 수 있는 상태는 어떤것인지 짐작이 간다. 상품목록 API응답에서는 detail 과 order로 이동할 수 있다. 개발자의 입장에서도 API를 보면 다음 상태가 어떻게 변화할 수 있는지 예측이 가능하다.

두번째 느슨한 결합은, API 컨슈머 쪽에서 detail을 응답 받기위한 URL을 저장하지 않고 href 값을 얻어와 호출한다는 뜻이다. 그렇게 구현함으로서 컨슈머는 API 엔드포인트의 변화로부터 자유로워진다. (장점을 이렇게 적다보니 미래의 API에 적용하고 싶은 맘이 든다 위험하다. 하지만 이 포스트는 분명히 적용하지 않아도 좋다는 주장을 하기위함이다.)

</pre>
<pre>{
  "links": [
    {
      "rel": "detail",
      "href": "http://server/api/items/12345"
    },
    {
      "rel": "order",
      "method": "post",
      "href": "http://server/api/items/order"
    }
  ]
}</pre>
<pre>

하지만 그럼에도 불구하고 REST API의 사용 주체가 빠른 속도의 의사결정과 개발을 중시하는 웹 서비스 업체라면, 너무 아카데미컬한 주제에 파뭍혀 실제 문제를 해결하는데 집중하지 못한다는 비난을 들을 수도 있을 것 같다. 오히려 이런 문제들 때문에 GraphQL같은 대안들이 나오게 된것이 아닐까?

물론 이런 REST가 추구하는 이상은 소프트웨어 엔지니어로서 성취하고 싶은 것이나, 회사원으로서 서비스의 전개 속도도 빠트릴 수 없는 부분이다. 그래서 슬며서 이슈를 던져보고 대부분 사람들이 쉽게 이해하지 못한다면 HATEOAS는 적용하지 않는게 좋겠다는 결론을 얻었다.

Restful API를 문서화를 도와주는 swagger API같은 도구들도 오히려 HATEOAS의 도입을 저하시키는 이유가 된다. 개발자가 손쉽게 전체 API엔드 포인트를 파악할 수 있으니 어떤 가정을 가지고 API 를 탐색하게 되고 이것은 강한 결합으로 이루어진다. (예를들어 swagger 페이지를 보고 상품 목록은 GET /items, 상품 상세 정보는 GET /items/1 과 같은 유추가 가능하다. HATEOAS 개념을 이용하면 상품 목록 리소스에서 전환 가능한 변화들이 link에 나타나야 한다. ).

물론 swagger를 사용해도 HATEOAS정보인 link 를 참조하는 것이 가능하나, link 사용을 클라이언트에게 강조하는 것이 원천적으로 불가능하기 때문에, API 컨슈머가 특정 가정을 가지고 (= 결합) API를 사용해도 막을 방법이 없다.

로이필딩이 인정하지 않는 REST API 면 어떠한가, 실제 HATEOAS나 REST성숙도 레벨 3까지에 대한 이해가 존재하지 않는 조직이라면 원작자의 의도를 무시하고 RPC스타일로 사용할것이 확실하다.

REST 아키텍쳐 레벨 3단계, HATEOAS 를 꼭 적용해야 할까?

HATEOAS가 이루고자 하는 이상과 현실의 차이가 존재한다. 개발과 의사결정 속도가 중요한 조직에서는 쓰지 않아도 좋다.

HATEOAS의 장점

관련 링크들