HATEOAS( Hypermedia as the Engine of Application State )implementation 'org.springframework.boot:spring-boot-starter-hateoas'。
API의응답에서 다른자원에 대한하이퍼링크를 포함한HAL Response로 응답하여클라이언트가 동적으로자원을탐색할 수 있도록 하는 개념.
▶REST API를 이용하는클라이언트가서버와동적상호작용이 가능하도록 설정
。REST 아키텍처중Uniform Interface에서HATEOAS가 정의
▶API는HATEOAS도 함께 구현해야RESTful API라고 할 수 있음
REST
。클라이언트가서버 API를요청시서버는자원과 함께클라이언트가 다음에 행할추가적인 요청(=Action)에 대한URI(=link)까지 함께HAL Response에 포함하여응답
▶ 수신된URI를 통해클라이언트는Application State를 다음요청으로transfer하여 후속 작업을 수행하는것이 가능
swagger를 포함하는Spring Docs와 함께 사용 시Spring Boot 3.4.3이하로 다운그레이드
。2025-10-31기준Springdocs 2.7.0은Spring Boot 3.4.3의HATEOAS를 지원
Controller에HATEOAS적용하기
WebMvcLinkBuilder의 모든static method를 import
import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.*;
Controller에서EntityModel 객체생성 및 반환
。id에 해당하는 특정데이터를 검색 시 해당데이터뿐만 아닌 모든데이터에 대해 검색하는/members URL의하이퍼링크도 함께반환
▶ 반환할DTO 객체를 포함하여EntityModel.of(DTO객체)로EntityModel 객체를 생성 및 다른Controller에매핑한URL을 저장하는링크 객체를 추가.
▶EntityModel객체.add(Link객체.withRel("관계명칭"));@GetMapping("/members/{id}") @ResponseStatus(HttpStatus.OK) public EntityModel<MemberReadResponse> getMember(@PathVariable int id){ // loginid에 해당하는 계정 가져오기 MemberReadResponse memberreadresponse = memberservice.getMember(id); // HATEOAS 구현을 위한 EntityModel 생성 EntityModel<MemberReadResponse> entityModel = EntityModel.of(memberreadresponse); // 특정 Controller로 접근하는 하이퍼링크를 포함하는 링크객체 생성 WebMvcLinkBuilder linkToMembers = linkTo(methodOn(MemberController.class).getAllMembers()); // EntityModel에 링크객체 추가 entityModel.add(linkToMembers.withRel("모든 멤버 조회")); // 계정과 하이퍼링크를 포함하는 EntityModel 반환 return entityModel; }
。"_links"아래getAllMembers() 컨트롤러에 대해매핑된URL을 포함한하이퍼링크가 생성
▶ 다음하이퍼링크를 클릭 시WebMvcLinkBuilder linkToMembers = linkTo(methodOn(MemberController.class).getAllMembers());를 통해 정의된 해당getAllMembers() 메서드로API 호출수행
HAL (JSON Hypertext Application Language):
。Spring에서HATEOAS구현을 위해API의 각각의자원에 대한HyperLink를JSON으로 생성하는 일관적인 방법을 제공하는 format.
▶"_links"라는 요소를 생성하여 여러link를 정의하면서REST API의 다른Resource에 연결하는 방법을 정의.
EntityModel<T>:org.springframework.hateoas
。RepresentationModel을 상속하는클래스
▶RepresentationModel은WebMvcLinkBuilder이 생성하는Link 객체를 담고,EntityModel은 해당Link 객체를 가진Resource 객체를 포함
。Spring HATEOAS에서는EntityModel을 이용해Response에 사용할Resource 객체를캡슐화및Link 객체를 등록
▶Client에게 접근할 수 있는자원에 대한hyper link를 추가 제공하여RESTful Response를 생성.
org.springframework.hateoas.Link
。Controller Method에매핑된URL을 포함하여WebMvcLinkBuilder에 의해객체가 생성되어EntityModel에 추가하여HATEOAS를 구현하는클래스
。하드코딩을 통해URL를 직접 입력하여링크객체생성이 가능하지만, 추후컨트롤러에 매핑된URL을 변경하는 경우 수동으로 변경해야하는 번거로움 존재
링크객체.withRel("관계명")
。EntityModel에 추가 시HATEOAS에 의해하이퍼링크가 도출될때의관계명을 작성
WebMvcLinkBuilder
。다른자원에 접근하는Controller Method에매핑된URL을 포함하는링크 객체를 자동생성하기위해 사용하는클래스
。Controller method를 기반으로static method를 사용하여 자동으로Link 객체를 생성
▶ 생성된링크객체를entityModel.add(링크객체)로EntityModel에 포함 및 반환하여HATEOAS구현
WebMvcLinkBuilder static method
ex )WebMvcLinkBuilder linkToMember1 = linkTo(methodOn(MemberController.class).getAllMembers());
WebMvcLinkBuilder.linkTo(컨트롤러메서드)
。해당자원에 관한hateoas.Link객체를 생성.
WebMvcLinkBuilder.methodOn(컨트롤러클래스의 Class객체)
。Controller class의Controller method를 참조하는데 사용
