[ Spring in Action ] HATEOAS 란?

Spring in Action 을 읽고, 필요한 부분 정리한 글입니다. 

---

 

HATEOAS : Hypermedia As The Engine Of Application State

클라이언트 요청에 대한 응답으로, 요청한 리소스와 관련된 하이퍼링크를 같이 제공하여, 서버와 클라이언트의 독립성을 높인다. 이뿐만이 아니라, 애플리케이션이 어떻게 동작하는지 사전지식이 없어도, 해당 리소스를 확인하고 링크들을 통해, 접근가능한 동작들을 확인하고 호출할 수 있도록 제공한다.

 

서버와 클라이언트의 독립성을 어떻게 높이나? 

예를들어, 서버에서 제공하는 리소스를 사용하기 위해, 클라이언트 측에서 하드코딩(문자열로 작성한 URL 주소)하여, 리소스 요청 기능을 개발했다.

그런데 서버 측에서 리소스 요청에 대한 경로를 변경했다고 하자. 

그렇다면, 클라이언트는 URL 변경으로 인해, 모든 리소스 요청을 다시 변경해야 한다. 

즉, 클라이언트는 기능적인 변경이 없음에도 불구하고, 서버 측의 URL 변경으로 인해, 수정 사항이 발생하게 된다. 

이러한 문제를 해결할 수 있도록 제공하는 것이 HATEOAS 이다.

 

사전지식 없는데, 접근 가능한 동작들을 어떻게 확인할 수 있나?

HATEOAS 는  호출하는 리소스에 대한 링크만을 제공하는 것이 아니다. 해당 리소스에서 가능한 동작들에 대한, 링크들도 함께 제공한다.

예를 들어, 특정 계좌 account를 조회 했을 때, 입금, 출금, 이체가 가능하다면, account 리소스를 호출하므로써, 클라이언트 측에 입금, 출금, 이체 동작이 가능함을 링크로 확인할 수 있도록 해줘야 한다. 그렇게 하면, 사전에 account가 입금, 출금, 이체 동작이 가능한지 확인하지 않더라도, 응답 내용의 링크들을 통해, 실행 가능한 동작들을 클라이언트가 확인할 수 있다.

[ 위키피디아 - HATEOAS ]

 

 

HAL : Hypertext Application Language

JSON 또는 XML 응답에 하이퍼링크를 포함시킨 형태 

 

[ 위키피디아 - HAL  Example ]

 

 

 

 

Spring HATEOAS

- 하이퍼링크를 Spring에 제공하는 라이브러리

 

implementation 'org.springframework.boot:spring-boot-starter-hateoas'

 

 

---

 

- 두 가지 타입의 하이링크 리소스 제공 

Resource : 단일 리소스 

Resources : 리소스 컬렉션

컨트롤러에서 응답할 때, JSON(또는 XML)에 링크를 포함여 전달함.

※ 기존 컨트롤러에서 반환 타입이 List<Taco> 였다면, Resources<Resource<Taco>> 로 반환되도록 수정해야 한다.

 

- 링크빌더 제공 

리소스에 링크를 제공하기 위해, URL을 하드코딩하게 되면, 추후 URL 변경 시, 작성했던 URL을 다시 수정해야 하는 번거로움이 생긴다. 그래서, 스프링 HATEOAS에서는 링크빌더를 제공하여, ControllerLinkBuilder 를 이용해 URL을 하드코딩하지 않는 방법을 제공한다.

 

-  ResourceSupport, ResourceAssemblerSupport 로 링크를 포함하는 리소스 제공

컨트롤러에서 리소스 반환 시, Resource/Resources 객체로 반환하기 위한 Resource 클래스 제공

ResourceAssemblerSupport :  ResourceSupport 인스턴스 생성을 자동화하고 자체 링크가 항상 추가되도록 하는 클래스

( List로 되어 있는 도메인 객체일 경우, List 의 객체 하나하나 마다 Resource로 변환해야 하는 수고를 덜기 위해 사용됨 )

ResourceSupport : DTO가 링크를 수집하기 위한 기본 클래스

 

- @Relation 을 이용해 embedded 관계 이름 짓기

HAL 응답을 보면, _embedded 는 호출한 리소스의 최상위 이름이다. _embedded가 포함하는 리소스의 필드 이름들을 보면, 기본적으로 클래스 명, 메서드 명에 의해 생성되는 것을 알 수 있다. 그러나 해당 필드 이름들은 클래스나 메서드 명칭이 변경되면 클라이언트 측도 변경해야 한다. 따라서 @Relation을 이용하여, 클래스 명을 변경하더라도, 응답 내용에는 변경되지 않게 하려면, @Relation 을 적용하여, value, collectionRelation 속성을 설정해야 한다.

 

---

 

+ 추가글 

Resource, Resouces, ResourceSupport, PagedResources 클래스의 명이 변경되었다.

내가 보고 있는 책에는 Resource, Resources 등의 클래스로 설명하지만, 막상 예제를 실행하려 보니, 관련 클래스가 없었고, 찾아보니 클래스 명이 변경되었다. 그 쓰임새가 정의된 이름과 매칭이 되지 않기 때문에 변경되었다고 한다.

 

아래 내용을 참고하여, 변경된 클래스를 사용하면 된다. 아래 캡쳐된 클래스 외에도 ResourceAssembler -> RepresentationModelAssembler, toResource() -> toModel() 등 클래스 뿐만 아니라 사용 메서드 명칭도 변경되었으므로, 아래 링크를 확인하고 사용하자.

[ spring.io 공식 문서 - 변경된 클래스 명 ]

https://docs.spring.io/spring-hateoas/docs/current/reference/html/#reference

Spring HATEOAS - Reference Documentation

 

 

 

---

 

HATEOAS 적용 코드

↓

https://gitlab.com/mskim0ct/tutorial/-/tree/main/hateoas/src/main/java/com/example/hateoas/server

hateoas/src/main/java/com/example/hateoas/server · main · mskim / Tutorial

 

Reference

Spring in Action - Chapter6 REST 컨트롤러 작성하기 - 6.2 하이퍼미디어 사용하기

https://en.wikipedia.org/wiki/Hypertext_Application_Language

https://docs.spring.io/spring-hateoas/docs/current/reference/html/#reference

https://haruhiism.tistory.com/200

https://en.wikipedia.org/wiki/HATEOAS