02) HATEOAS와 Self-Describtive Message

1. HATEOAS

Hypermedia As The Engine Of Application State의 약자로, RESTful API를 설계할 때 사용되는 아키텍처 원칙 중 하나다.

HATEOAS 원칙에 따르면, 클라이언트는 서버로부터 받은 응답 내의 하이퍼미디어 링크를 통해 상태 전이를 할 수 있어야 한다. 이 말은, API를 사용하는 클라이언트가 서버의 리소스를 탐색하고 상호작용할 수 있는 링크 정보를 서버의 응답 내에 포함시켜야 한다는 뜻이다.

 

예를 들어 사용자 정보를 조회하는 API의 응답이라고 하자.

{
	"id": 1,
	"name": "홍길동",
	"email": "hong@example.com"
}

 

만약 이 API가 HATEOAS의 원칙을 따른다면 사용자의 정보를 바탕으로 다른 작업을 수행할 수 있는 링크 정보를 포함하고 있어야 한다.

클라이언트는 서버의 API 구조에 대한 사전 지식 없이도 서버로부터 제공받은 링크를 통해 필요한 작업을 수행할 수 있다. 클라이언트와 서버 간의 결합도를 낮추고, 서버의 변화에 대한 클라이언트의 유연성을 높이는 데 도움이 된다.

{
    "id": 1,
    "name": "홍길동",
    "email": "hong@example.com",
    "_links": [
		{
			"rel" : "self",
			"herf" : "http://localhost:8080/users/1"
		}, {
			"rel" : "update",
			"herf" : "http://localhost:8080/users/1/update"
   		}, {
   			"rel" : "delete",
			"herf" : "http://localhost:8080/users/1/delete"
		}
	]
}

 

1.1 HAL JSON

Hypertext Application Language

하이퍼미디어 기반의 JSON 또는 XML 형식을 사용하여 RESTful API의 리소스를 표현하기 위한 간단한 규약

 

 

 

 

2. Spring Rest Docs

Spring REST Docs

RESTful 서비스를 문서화하기 위한 도구

• 단위 테스트를 통해 문서를 생성하므로, 문서가 항상 최신 상태를 유지하고, 실제 코드와 일치하도록 보장
• 서버에 따로 배포할 필요 없이, 빌드 과정에서 자동으로 문서를 생성할 수 있습니다. 이렇게 생성된 문서는 웹 서버를 통해 호스팅 가능
  

기본적인 설정 방법은 위의 Spring REST Docs 공식문서에서 쉽게 설정이 가능하다. 기본적인 설정이 끝이 나면 위에서 말했던 것처럼 단위테스트를 통해 문서를 생성한다. 여기서 중요한 게 꼭 테스트 코드에 @ExtendWith(RestDocumentationExtentsion.class)을 붙여줘야 한다! 그렇게 테스트 코드를 실행하면 이렇게 adoc 파일들이 생긴다. 

doument(문서 이름, 문서 설명자)

• links: 응답에 포함된 링크를 문서화합니다. 링크의 rel과 description을 인자로 받습니다.
• requestHeaders: 요청 헤더를 문서화합니다. 헤더의 이름과 설명을 인자로 받습니다.
• requestFields: 요청 본문의 필드를 문서화합니다. 필드의 경로와 설명을 인자로 받습니다.
• responseHeaders: 응답 헤더를 문서화합니다. 헤더의 이름과 설명을 인자로 받습니다.
• responseFields: 응답 본문의 필드를 문서화합니다. 필드의 경로와 설명을 인자로 받습니다.

.andDo(document("create-event",
   links(
      linkWithRel("self").description("link to self"),
      linkWithRel("query-events").description("link to query-events"),
      linkWithRel("update-event").description("link to update-event"),
      linkWithRel("profile").description("link to profile")
),

위 경로에 index.adoc 파일을 생성한다. index.adoc는 문서의 내용, 구조 .. 등등을 설정할 수 있다. 나는 백기선 강사님이 만들어둔 틀을 사용한다. gradle에서 설정한 정보와 Asciidoctor을 통해 HTML문서로 변환해 설정한 위치에 파일을 생성해 준다. Spring REST Docs에서는 index.adoc 파일을 사용하여 API 문서의 메인 페이지를 작성한다.

이렇게 http://localhost:8080/docs/index.html 에 들어가면 이렇게 이쁘게 잘나온다.

 

 

 

✏️ 참고자료

• https://wonit.tistory.com/454
• https://www.youtube.com/watch?v=RP_f5dMoHFc&ab_channel=NAVERD2