HATEOAS와 Self-Descriptive Message 적용

HATEOAS

• 클라이언트가 서버가 제공하는 하이퍼미디어 링크와 상호 작용하여 웹 서비스의 리소스를 동적으로 탐색할 수 있도록 하는 REST 아키텍처의 제약 조건 ( Self-descriptive messages,  Dynamic navigation, Discoverability )
• 애플리케이션의 상태 정보에 따라 링크 정보가 동적으로 바뀜
  

  

  계좌에 대한 정보 뿐 아니라, 이후 클라이언트-서버 간 상호작용할 수 있는 링크 제공

  

  예금만 가능하도록 link가 동적으로 바뀜

  
  이러한 HATEOAS를 만족시켜야 진정한 REST API 다!

---

스프링 HATEOAS

이 프로젝트는 Spring, 특히 Spring MVC로 작업할 때 HATEOAS 원칙을 따르는 REST 표현을 쉽게 생성할 수 있는 몇 가지 API를 제공한다.

1. 링크를 만드는 기능
   • 문자열 가지고 만들기 ( new link() )
   • 컨트롤러와 메소드에 달려있는 url로 만들기 ( linkTo() )
2. 리소스를 만드는 기능 - extends EntityModel<T>
   • 리소스 = data(Resource) + Links
3. 클라이언트 입장에서 링크를 찾아주는 기능
   
   • Traverson
   • LinkDiscoverers

리소스의 구성

 

# 링크 구성

1. href
2. rel : 현재 리소스와의 관계
   • self (자기 자신에 대한 url을 넣어줄 때)
   • profile (응답 본문에 대한 문서)
   • ...각종 이벤트

 

스프링 HATEOAS 적용

응답 결과에 아래와 같이 링크 정보가 포함되길 원한다.

 

링크를 생성해주기 위해서 EntityModel (Resource(데이터+링크)를 의미)을 상속 받은 클래스를 만든다.

기본적으로 self 링크는 매번 사용되므로 추가해둔다.

 

컨트롤러에서 EntityModel을 상속받은 클래스를 객체로 만들고, 링크를 추가한 후 응답 body에 넣는다.

EntityModel을 상속받으면 _links가 응답에 추가된다.

 

 

응답 JSON

 

※ 응답 타입 application/hal+json

HAL(Hypertext Application Language): RESTful API 응답을 구조화하기 위해 사용되는 표준화된 JSON 또는 XML 형식. application/hal+json은 HAL의 JSON 표현 형식을 뜻하며, 클라이언트가 API 리소스와 그 하위 리소스 간의 관계를 쉽게 탐색할 수 있도록 도와준다.

HAL은 특히 API 리소스 간의 링크를 표준화된 방식으로 포함하므로, 클라이언트가 현재 응답뿐만 아니라 다른 관련 리소스의 경로를 쉽게 찾고 연동할 수 있게 한다. 가령, 특정 사용자 정보를 나타내는 JSON 응답에 사용자의 게시물, 팔로워 목록 등의 관련 링크를 함께 제공하는 경우 application/hal+json 형식의 응답은 아래와 같다.

{
    "name": "John Doe",
    "_links": {
        "self": { "href": "/users/123" },
        "posts": { "href": "/users/123/posts" },
        "followers": { "href": "/users/123/followers" }
    }
}

---

 

Spring REST Docs

Spring MVC test를 기반으로 문서 조각(snippet)을 만들어준다.

이 문서 조각을 모아서 REST API Document를 만들 수 있다.

 

REST Docs 코딩

• andDo( document(“doc-name”, snippets) )

REST Docs 자동 설정

• @AutoConfigureRestDocs

RestDocMockMvc 커스터마이징

• RestDocsMockMvcConfigurationCustomizer 구현한 빈 등록
• @TestConfiguration

 

스니펫 생성 후 api document를 만드는 과정

1. 테스트 코드에 .andDo( document(“doc-name”, snippets) )추가

andDo로 문서를 만들면 스니펫이 생성된다.

 

2. 스니펫 포맷팅

요청/응답 스니펫을 포맷팅하기 위해 설정 빈을 등록한다

 

 

3. 추가 스니펫 생성

링크, 요청/응답 헤더/필드에 대한 스니펫 생성

테스트를 돌리면 스니펫이 생성된다.

 

4. Document 생성 플러그인 설정

생성된 스니펫들을 기반으로 Document를 만들기 위한 플러그인 설정

 

5. 템플릿 파일 추가

이 템플릿에서 스니펫을 불러온다.

 

6. 문서 생성

추가 후 maven package 수행하면 html이 생긴다

generated-docs에 생긴 html을 static 밑으로 옮겨주는 플러그인 설정을 미리 추가해뒀었다.

 

7. self-descriptive 조건 충족

self-descriptive 한 API를 만들기 위해, 프로필 링크를 추가하여 스니펫을 만든다.

Controller

ControllerTest

---

참고 자료 & 이미지 출처
스프링 기반 REST API 개발 (백기선 님)
https://en.wikipedia.org/wiki/HATEOAS
https://docs.spring.io/spring-hateoas/docs/current/reference/html/

https://docs.spring.io/spring-restdocs/docs/2.0.2.RELEASE/reference/html5/

Spring REST Docs

 

Spring HATEOAS - Reference Documentation

 

HATEOAS - Wikipedia

 

Spring HATEOAS - Reference Documentation