REST API를 디자인할 때 주의해야 할 핵심 원칙 중 하나는 Self-Descriptiveness와 HATEOAS입니다. 이러한 원칙은 API의 설계와 사용성을 향상시키는 데 중요한 역할을 합니다.
Self-descriptiveness(자기 기술성)
Self-descriptiveness란 API가 전송하는 메시지 자체만으로도 그 의미를 해석할 수 있어야 함을 의미합니다. 이는 클라이언트가 메시지를 받고 해석할 때 추가적인 문서나 정보 없이도 명확한 이해를 할 수 있어야 한다는 것을 의미합니다. 예를 들어, JSON 형식의 데이터를 전송할 때는 Content-Type 헤더를 통해 해당 데이터의 미디어 타입이 명시되어야 합니다. 또한, 메시지에는 데이터의 의미를 설명하는 정보가 포함되어야 합니다.
HATEOAS(Hypermedia As The Engine Of Application State)
HATEOAS는 REST 아키텍처의 중요한 특성 중 하나로, Hypermedia를 통해 애플리케이션 상태의 전이를 제어하는 개념입니다. 즉, 클라이언트는 서버로부터 받은 메시지에 포함된 링크를 따라가면서 애플리케이션의 상태를 변경할 수 있어야 합니다. 이를 통해 클라이언트와 서버 간의 의사소통이 동적이고 유연하게 이루어질 수 있습니다.
REST API 디자인에서의 적용
REST API를 디자인할 때는 Self-descriptiveness와 HATEOAS를 만족시키기 위해 노력해야 합니다.
- 메시지에는 데이터의 의미를 명확히 설명하는 정보가 포함되어야 합니다.
- 링크를 통해 다음 가능한 상태 전이를 명시적으로 나타내어야 합니다.
API의 미디어 타입은 등록되어야 하며, 클라이언트가 해당 미디어 타입을 해석할 수 있어야 합니다. - API의 설계는 클라이언트와 서버가 독립적으로 진화할 수 있도록 유연성을 제공해야 합니다.
이러한 원칙을 따르면 REST API가 더욱 쉽게 이해되고 사용되며, 더욱 유연하고 확장 가능한 시스템을 구축할 수 있게 됩니다.
JSON은 Self-decriptiveness 와 HATEOAS를 만족하지 않기 때문에 REST 하지 못하다
1. Self-decriptiveness 측면:
request message만으로 "id", "title"이 무엇을 의미하는지 알 수 없다.
2. HATEOAS 측면:
다음 상태로 전이할 링크가 없다.
그럼 REST API로 고쳐보자
Self-decriptiveness
(1) Media type
- 미디어 타입을 하나 정의한다.
- 미디어 타입 문서를 작성한다.
- IANA에 미디어 타입 등록한다. 이 때만든 문서를 미디어 타입의 명세로 등록한다.
단점: - 매번 미디어 타입을 등록해야한다.
(2) Profile
Link 헤더에 profile relation으로 해당 명세를 링크한다.
단점:
- 클라이언트가 Link 헤더와 profile을 이해해야한다.
- Content negotiation을 할 수 없다.
(미디어타입이아니라 링크 헤더만으로 확인하는 것이기 때문에)
HATEOAS
(1) date로
단점:
- 링크를 표현하는 방법을 직접 정의해야함
- 기존 API를 많이 고쳐야함 (침투적)
(2) HTTP 헤더로 (Link, Location 등의 헤더로 링크를 표현)
단점:
- 정의된 relation만 활용한다면 표현에 한계가 있다.
=> data, 헤더 모두 활용하면 좋다.
Media type을 IANA에 등록하면 좋은점
- 누구나 쉽게 사용 가능
- 이름 충돌 피할 수 있음
- REST의 저자 로이 필딩은 방법 이 쉽다고 나오지만, 그렇지 않은 것 같다.
정리
- 오늘날 대부분의 REST API는 사실 REST를 따르지 않고 있다.
- REST를 따를 것인지는 API를 설계하는 이들이 스스로 판단하여 결정해야한다.
- REST를 따르겠다면, Self-decriptive와 HATEOAS를 만족시켜야한다.
- Self-decriptive는 custom media type이나 profile link relation 등으로 만족시킬 수 있다.- HATEOAS는 HTTP 헤더나 본문에 링크를 담아 만족시킬 수 있다.
- REST를 따르지 않겠다면, "REST를 만족하지 않는 REST API"를 뭐라고 부를지 결정해야 한다.
- HTTP API라고 부를 수도 있고
- 그냥 이대로 REST API라고 부를 수도 있다.
[참고]
