[Spring] API 구현을 위한 Hateoas 적용

 

 

Hateoas

Hateoas는 Hypermedia As The Engine Of Application State의 약자다.
하이퍼미디어를 애플리케이션의 상태를 관리하기 위한 매커니즘으로 사용한다.
Hateoas는 Rest Api를 사용되는 클라이언트가 서버와 동적인 상호작용을 가능케한다.
클라이언트가 서버에게 요청을 할 때, 요청에 필요한 URI를 응답에 포함시켜서 반환한다.
예를 들어, 사용자 정보를 생성(POST)하는 요청 이후, 이를 조회, 수정, 삭제할 때, 이러한 모든 동작을 URI를 이용해 동적으로 알려준다는 의미입니다.

Hateoas는 REST API를 잘 설계하기 위해 나온 개념이다.
REST API는 웹 애플리케이션이 제공하는 데이터를 리소스, 즉 자원으로 간주하고 각각의 자원에 고유한 URI를 할당함으로써 이를 표현하는 API를 정의하기 위한 소프트웨어 아키텍처 스타일이다.

Hateoas 공식 문서 : https://docs.spring.io/spring-hateoas/docs/current/reference/html/#reference

잘 설계된 REST API는 구현하기 위한 단계가 존재한다.

REST 구현 단계

1단계 :  리소스 도입
- 서버가 가진 모든 데이터를 하나의 자원으로 관리하며 고유한 URI를 제공함으로써 클라이언트가 하나의 단일 API 엔트포인트가 아닌 각 자원과 직접 커뮤니케이션을 할 수 있도록 한다.
2단계 : HTTP 동사
- HTTP 동사를 이용하여 자원에 대해 수행하고자 하는 작업의 종류를 표현한다.
3번 : 하이퍼미디어 컨트롤
- Hateoas라는 개념을 통해 해당 자원에 대한 호출 가능한 API에 대한 정보를 자원 상태를 반영하여 표현한다. 자원 상태에 따라 서버가 클라이언트에게 동적으로 정보를 제공할 수 있다.

 

 

마지막 단계가 Hypermedia Controls (하이퍼미디어 컨트롤) - Hateoas 개념을 통해 자원에 호출 가능한 API 정보를 자원의 상태를 반영하여 표현한 것이다.

REST API 구현 단계별 예시

Hateoas 사용 전 / 후 비교

Hateoas 사용 전

Hateoas 사용 후

Hateoas를 사용하면 클라이언트 사이드에서 'rel'의 이름으로 요청 URI를 사용하기 때문에 URI를 수정해도 클라이언트 사이드 수정이 이뤄지지 않는다.

 

Hateos 사용 예시

📌 User

@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {

    private Long id;

    @Size(min = 2, message = "Name은 2글자 이상 입력해 주세요.")
    private String name;

    @Past  // 과거 날짜만 가능하도록 제약
    private LocalDateTime joinDate;

    private String password;
    private String ssn; // 주민등록번호

}

📌 UserController

@RestController
@RequiredArgsConstructor
public class UserController {

    private final UserDaoService service;

    @GetMapping("/users")
    public List<User> retrieveAllUsers() {
        return service.findAll();
    }

    @GetMapping("/users/{id}")
    public EntityModel<User> retrieveUser(@PathVariable Long id) {
        Optional<User> userOptional = service.findOne(id);

        if (userOptional.isEmpty()) {
            throw new UserNotFoundException(String.format("ID[%s] not found", id));
        }

        User findUser = userOptional.orElse(null);

        // HATEOAS
        EntityModel<User> model = EntityModel.of(findUser);
        // 링크 생성
        WebMvcLinkBuilder linkTo = WebMvcLinkBuilder.linkTo(
                WebMvcLinkBuilder.methodOn(this.getClass()).retrieveAllUsers());
        // 링크 추가
        model.add(linkTo.withRel("all-users"));

        return model;
    }

    ...


}

EntityModel<T>

• 도메인 객체를 감싸고 그 외 링크를 추가하는 객체다.
• add() : 링크 추가 메서드

WebMvcLinkBuilder.linkTo() :  컨트롤 클래스를 가리키는 WebMvcLinkBuilder 객체를 반환한다.
WebMvcLinkBuilder.methodOn() : 타겟 메서드의 가짜 메서드 콜이 들어있는 컨트롤러 프록시 클래스를 생성한다. 직접 메서드 객체를 만드는 것보다 유연한 표현이 가능하다.

 

 

 

 

---

👀 참고 자료

https://joomn11.tistory.com/26

[Hateoas] Hateoas(헤이티오스) 란 ( + REST API란 )

 

https://kkambi.tistory.com/126

[spring] 스프링 부트의 Hateoas 지원

 

https://m.blog.naver.com/tmondev/220391644590

Hypermedia-driven REST API