[Spring Boot/RESTful] REST API 3단계를 위한 HATEOAS 설정

HATEOAS

Hypermedia As the Engine Of Application State

현재 리소스와 연관된(호출 가능한) 자원 상태 정보를 제공(mapping)

클라이언트가 명시적으로 링크를 작성하지 않아도 서버 측에서 받은 링크의 레퍼런스를 통해 어플리케이션의 상태 및 전이를 표현할 수 있다. 

 

장점

- 요청 URI가 변경되더라도 클라이언트에서 동적으로 생성된 URI를 사용함으로써, 클라이언트가 URI 수정에 따른 코드를 변경하지 않아도 되는 편리함을 제공한다.
- URI 정보를 통해 들어오는 요청을 예측할 수 있게 된다.
- Resource가 포함된 URI를 보여주기 때문에, Resource에 대한 확신을 얻을 수 있다.

 

 

REST API 설계 단계

0. The Swamp of POX

특정한 웹 프로토콜(SOAP, XML-RPC)을 통해서 컴퓨터가 가지고 있는 자원을 의미 없이 전달. POST 메소드만 사용하며, 서비스 간에 단일 POST 메소드로 XML 데이터를 교환한다. 

1. Resources

함수에 파라미터를 넘기는 대신 REST URI를 이용한다. POST 메소드 하나밖에 사용하지 않지만, POST 메소드로 서비스간 통신을 하면서 복잡한 기능을 여러 리소스로 분산시킨다. 

2. HTTP Verbs

POST 이외에도 GET, DELETE, PUT, HEAD 메소드를 추가적으로 사용한다. 

3. Hypermedia controls

요청에 대한 Hypermedia 응답 속에 클라이언트가 다음에 취해야 할 액션에 대한 상태 정보가 담겨 있다. 리소스의 정보를 추가적으로 사용할 수 있는 리소스와 함께 전달한다. 하지만 resource뿐만 아니라 부가적인 정보까지 나타낸다는 점에서 논란이 있다.

 

 

HATEOAS 사용

1. dependency 추가

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-hateoas</artifactId>
</dependency>

2. 버전별 HATEOAS implementation 확인

pom.xml 제일 상단을 보면 스프링부트 버전 확인 가능

<parent>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-parent</artifactId>
	<version>2.6.3</version>
	<relativePath/> <!-- lookup parent from repository -->
</parent>

spring 2.1.8 RELEASE

• Resource : 만들고자 하는 추가 자원을 Resouce 객체로 넣음
• ControllerLinkBuilder : 링크해줌

@GetMapping("/users/{id}")
public Resource<User> retrieveUser(@PathVariable int id){

	Resource<User> resource = new Resource<>(user);
	ControllerLinkBuilder linkTo = linkTo(methodOn(this.getClass())
    				.retrieveAllUsers());
	resource.add(linkTo.withRel("all-users");

	return resource;
}

spring 2.2

• EntityModel
• WebMvcLinkBuilder : 유제 객체를 반환시킬 때 유저가 사용할 수 있는 추가적인 정보(링크)를 hypermedia 형식으로 넣어놓는다.
  • linkTo, methodOn 함수를 사용하기 위해서는 import 시 static을 붙여줘야 한다
  • linkTo() : 컨트롤러 클래스를 가리키는 WebMvcLinkBuilder 객체를 반환 
  • methodOn(연결시킬 메소드) : this.getClass()가 가지고 있는 데이터 중에서 retrieveAllUsers() 메소드를 연동

@GetMapping("/users/{id}")
public Resource<User> retrieveUser(@PathVariable int id){

	// 매개변수에 유저 객체값 넣음
	EntityModel<User> entityModel = EntityModel.of(user);
	WebMvcLinkBuilder linkTo = linkTo(methodOn(this.getClass()).retrieveAllUsers());

	// retrieveAllUsers() 메소드를 "all-users"로 href 연결
    	// resource 객체에 링크 추가
	entityModel.add(linkTo.withRel("all-users"));
        
	return model;
}

retrieveAllUsers()와 all-users 연동 → /users와 all-users mapping

 

[참고]

HATEOAS 설명

[Spring Boot] RESTful Service 강의 정리 (6) - Implementing HATEOAS / level3단계의 REST API 구현

리처드슨 성숙 모델