[실습] Self Descriptive 와 HATEOAS

들어가며

Self-Descriptive 란 말 그대로 메시지가 스스로 설명이 되어야 한다는 뜻이다. 응답 메시지의 요소만 보고 그 뜻을 알 수 있어야 한다. 만약 서버의 API 가 변경되거나 URI 가 변경되는 등 기능이 수정된다 하더라도 클라이언트는 문제 없이 돌아가야 한다. 이럴 때 서로서로 Self-Descriptive messages 를 활용한다면 개발자가 요청의 의미를 쉽게 파악할 수 있어 이해도를 높일 수 있다. 결론적으로 REST API 를 구현하는데 Self-Descriptive 는 API 의 이해도, 유지보수성, 재사용성을 높이는 데 중요한 역할을 한다.

Self Descriptive

RESTful 아키텍처의 제약사항 중 하나로, 클라이언트가 추가적인 문서 없이도 응답 메시지만 보고 그 의미를 이해할 수 있도록 하는 개념이다. 아래 방법으로 만족할 수 있다.

✅ HTTP 상태 코드 활용 : 일반적인 웹 개발을 한다면 지켜지는 내용이다.
✅ Content-Type 및 Accept 헤더 활용 : Content-Type 은 응답할 body 가 있는 경우 붙여주면 된다.

HTTP/1.1 200 OK
Content-Type: application/json
[ { "id": "example123", "name": "홍길동" } ]

여기까지는 문제가 없겠지만… 위 예시를 자세히 살펴보면 id, name 이 무엇을 의미하는가에 대한 해설은 없다. 이 경우 Self Descriptive 에 위배된다 볼 수 있다. 이를 해결하기 위해서는 아래 3가지 방법을 생각해볼 수 있다.

방법 1. media-type 정의

IANA 에 미디어 타입을 등록할 수 있다. id 가 무엇이고 name 이 무엇인지 정의하여 등록하면 되고, 이 메시지를 받는 사람은 명세를 찾아갈 수 있으므로 의미를 온전히 해석할 수 있게 된다. 그러나 매번 media type 을 정의하는 것은 매우 비효율적이라 할 수 있다 …

방법 2. profile 링크 헤더

id, name 이 무엇인지 정의한 문서를 작성하여 Link 헤더에 profile relation 으로 해당 명세를 링크하는 방법이다. 이 경우 클라이언트가 Link 헤더와 profile 을 이해해야 한다. 그런데 profile 링크 헤더는 브라우저에서 지원하지 않는다고 한다 (!!!)

방법 3. HAL 의 링크 데이터에 profile 링크 헤더 추가

매번 media type 을 정의하는 게 번거롭고, profile 링크 헤더는 브라우저에서 지원하지 않기 때문에 HAL(Hypertext Application Language)에 명세의 링크를 추가하는 방법을 사용하는 방법을 추천한다. 이를 HATEOAS 라고 하는데…

HATEOAS (hypermedia as the engine of application state)

현재의 URI 에서 다음으로 전이될 수 있는 URI 를 표시해주는 것을 말한다. 클라이언트를 개발하는 사람들이 특정 메서드로부터 올 수 있는 결과를 예측하는 것이 가능해지고, API 가 변경되더라도 기존의 링크를 통해 새로운 엔드포인트를 찾아서 작업을 할 수 있기 때문에 클라이언트 측 코드를 수정할 일이 적어진다.

예시를 통해 알아보자.

< HTML 의 경우 >

#예시
GET / todos HTTP/1.1
Host: example.org

HTTP/1.1 200 OK
Content-Type : text/html

<html>
<body>
<a href="https://todos/1"> 회사 가기</a>
<a href="https://todos/2"> 집에 가기</a>
<body>
<html>

✅ Self-Descriptive : 모든 태그는 해석 방법을 구체적으로 찾을 수 있고, 힌트만을 단서로 해석할 수 있다.
✅ HATEOAS : a 태그를 통해 다음으로 전이될 페이지를 명시함.

< JSON 의 경우 >

GET / todos HTTP/1.1
Host:L exampele.org

HTTP/1.1 200 OK
Content-Type: application/json
[
  {"id": 1, "title": "회사 가기"},
  {"id": 2, "title": "집에 가기"},
]

❌ Self-Descriptive : id 가 무엇을 의미하는지, title 이 무엇을 의미하는지 알 길이 없음.
❌ HATEOAS : 다음으로 전이될 페이지가 무엇인지 명시되어 있지 않음.

🔖 참고자료

RESTful API 구현하기

REST API란?