HATEOAS

RESTful API를 설계할 때, RMM (Richardson Maturity Model) 단계를 따라서 API를 업데이트 할 수 있다.

REST API를 설계할 때, 레벨 단계를 따라서 API를 업데이트 할 수 있다.

• Level 0 : The Swamp of POX

  • 서버의 리소스. 즉, 데이터를 웹 서비스 형태로 제공하기 위해 단순 URI 매핑 형태만 가진다.

  • http://domain/deleteArticles

• Level 1 : Resources

  • 서버의 자원을 리소스 (서버가 제공하는 자료)화 할 수 있는 단계를 얘기한다.

  • 외부로 공개하고자 하는 리소스를 좀 더 의미있는 URI로 표현한다.

  • POST와 같은 메소드로 처리하고 모든 반환 코드를 200OK로, 단순 케이스로 반환한다.

  • http://domain/article/1

• Level 2 : HTTP Verbs

  • HTTP 상태코드, 메소드 등을 적절히 이용해서 리소스를 제공할 수 있는 단계이다.

  • HTTP 메소드를 이용해서 리소스를 사용 및 적절한 URI, 엔드포인트, 상태코드 제어

  • Level 1에서 제시하는 방법 + HTTP Methods에 맞게 설계한다.

    • 리소스의 상태가 변경할 수 없는 읽기 형태면 GET을 사용한다든가.

    • HTTP에서 사용하는 Method를 가지고 API를 분리해서 사용

  • 데이터를 조작하는 CRUD를 이용해 서비스함

    • 비슷한 URI가 발생한다 하더라도 HTTP Method에 따라서 상태나 서비스를 분류할 수 있다.

• Level 3 : Hypermedia Controls

  • HATEOAS 기능을 연결되어 있는 단계를 얘기한다.

    • Level 2 + HATEOAS

  • 다음 작업으로 어떤것을 할 수 있는지, 현재 작업에서 할 수 있는 행동들이 어떤것이 있는지, 해당 작업을 통해 다뤄질 수 있는 작업이 어떤것들이 있는지 제공

    • 서버의 다음 동작을 미리 알려줄 수 있다.

spring에서 제공하는 라이브러리를 사용할 수 있다.

• org.springframework.boot:spring-boot-starter-hateoas

@GetMapping("/users/{id}")
public EntityModel<User> retrieveUser(@PathVariable int id) {
	User user = ~;
	...
	
	// 해당 메소드가 반환할 body data
	EntityModel entityModel = EmtitiModel.of(user);
	
	// 해당 API는 단일 사용자를 반환하는 API이다.
	// 하지만 link를 설정해서 전체 유저를 반환하는 API도 명시해준다.
	WebMvcLinkBuilder linTo = 
		WebMvcLinkBuilder.linkTo(
			WebMvcLinkBuilder.methodOn(
				this.getClass())
				.retrieveAllUsers()
			)
		);
						
	// all-users -> http://localhost:8080/users
	entityModel.add(linTo.withRel("all-users")); 
	
	return entityModel;
}

HATEOAS

HATEOAS가 말하는 것은 다음과 같다.

• Hypermedia (링크)를 통해서 애플리케이션의 상태 전이가 가능해야 한다.

• Hypermedia에 자기 자신에 대한 정보가 담겨야 한다.

• 즉, 현재 리소스와 연관된 (호출 가능한) 자원 상태 정보를 제공하는 것이다.

🤔 그럼 상태 전이? 이게 무슨 의미일까.

GET https:*//my-server.com/article*

예를 들어서 게시글을 조회하는 URI가 존재할 때, 글을 조회한 사용자는 다음 행동으로 무엇을 할까?

• 다음 게시물을 조회

• 이전 게시물 조회

• 댓글 달기

{
  "data": {
    "id": 1000,
    "name": "게시글 1",
    "content": "HAL JSON을 이용한 예시 JSON",
    "self": "http://localhost:8080/api/article/1000", // 현재 api 주소
    "profile": "http://localhost:8080/docs#query-article", // 해당 api의 문서
    "next": "http://localhost:8080/api/article/1001", // 다음 article을 조회하는 URI
    "comment": "http://localhost:8080/api/article/comment", // article의 댓글 달기
    "save": "http://localhost:8080/api/feed/article/1000", // article을 내 피드로 저장
  },
}

이러한 행동들이 바로 상태 전이가 가능한 것들인데, 이런것을 “응답 본문”에 넣어줘야 한다.

• 바로 Hypermedia (링크)를 통해 넣어준다.

이를 통한 이점은 다음과 같다.

1. API 버전을 명시하지 않아도 된다.

2. 링크 정보를 동적으로 바꿀 수 있다.

3. 링크를 통해 상태 전이를 쉽게 할 수 있다.

이게 바로 Uniform Interface 제약 조건을 만족시키는 REST API라고 할 수 있는것이다.

하지만 “HAL JSON”을 이용하기 전까지 완벽하지 않다.

HAL

Hypertext Application Language 으로 JSON, XMl 코드 내의 외부 리소스에 대한 링크를 추가하기 위한 특별한 데이터 타입이다.

HAL은 두 개의 타입을 갖는다.

1. application/hal+json

2. application/hal+xml

이 HAL 타입을 이용한다면 쉽게 HATEOAS를 달성할 수 있다.

HAL 타입에서는 두 가지(리소스, 링크)의 특징만 이용하면 된다.

리소스 : 일반적인 data 필드

링크 : Hypermedia로 _self 필드가 링크에 포함된다.

{
  "data": { // HAL JSON의 리소스 필드
    "id": 1000,
    "name": "게시글 1",
    "content": "HAL JSON을 이용한 예시 JSON"
  },
  "_links": { // HAL JSON의 링크 필드
    "self": {
      "href": "http://localhost:8080/api/article/1000" // 현재 api 주소
    },
    "profile": {
      "href": "http://localhost:8080/docs#query-article" // 해당 api의 문서
    },
    "next": {
      "href": "http://localhost:8080/api/article/1001" // article 의 다음 api 주소
    },
    "prev": {
      "href": "http://localhost:8080/api/article/999" // article의 이전 api 주소
    }
  }
}

참고 : https://wonit.tistory.com/454