URL 작성의 어려움 - HATEOAS

문제 상황

 

프로젝트를 진행하다가 URL 작성의 어려움을 겪었다.

 

내 프로젝트에는 Diary라는 엔티티와 Sleep이라는 엔티티가 있다.

그리고, 내가 작성하려는 URL에는 두 자원이 포함되어 있어야 한다.

하지만, 이 자원들은 내가 지금까지 작성해왔던 URI들과는 다르게 둘의 관계가 계층 관계가 아니라 서로 독립적인 관계이다.

 

따라서, 이러한 경우에는 '어떻게 URL을 작성하면 좋을 까?' 라는 생각에서 이 포스팅을 작성하게 되었다.

 

관련 개념 및 해결의 실마리

 

리소스가 단일 실제 데이터 항목을 기반으로 할 필요는 없다.

 

단순히 데이터베이스의 내부 구조를 반영하는 API를 만들지 마라! 

 

REST의 목적은 엔티티 및 해당 엔티티에서 애플링케이션이 수행할 수 있는 작업을 모델링하는 것입니다.

 

컬렉션 및  항목에 대한 URI를 계층 구조를 구성하라

하지만 이러한 구조가 복잡해질 경우에 HTTP 응답 메시지의 본문에 연결된 리소스에 대한 탐색 가능한 링크를 제공한다.

 

이 매커니즘을 HATEOAS를 사용하여 '관련 리소스 탐색'이라고 한다.

 

HATEOAS

 

HATEOAS(Hypertext as the Engine of Application State)는 각 요청에 대한 응답은 한 상태에서 다른 상태로 바꾸는 데 필요한 정보를 포함하고 있어야 하는 원칙입니다.

 

각 HTTP GET 요청은 응답에 포함된 하이퍼링크를 통해 요청된 개체와 직접 관련된 리소스를 찾는 데 필요한 정보를 반환해야하며, 이러한 각 리소스를 사용할 수 있는 작업들에 대한 정보들도 같이 제공해야합니다.

 

 

해결

 

리소스가 실제 데이터 항목을 기반으로 할 필요가 없고, Rest의 목적(애플리케이션이 수행할 수 있는 작업)을 고려하여

아래와 같은 URL을 명명하였습니다.

 

제 프로젝트의 경우에 calendar에서 날짜를 바탕으로 해당 날짜와 관련된 정보들을 가져올 수 있는 기능이 있기 때문에 아래와 같이 URL을 명명하였습니다.

 

@GetMapping("/calendar/{date}")

 

또한, 위 URHATEOUS를 적용하여 위의 URL로 요청시 아래와 같은 응답을 하게 만들었습니다

 

 

 

 

이상입니다!

---

 

참고 자료

 

웹 API 디자인 모범 사례 - Azure Architecture Center | Microsoft Learn

웹 API 디자인 모범 사례 - Azure Architecture Center