실습

HATEOAS 란?

• HATEOAS (Hypertext as the Engine of Application State) = 애플리케이션 상태의 엔진으로서의 하이퍼텍스트

• 쉽게 말해, API에서 클라이언트가 다음 단계들에 대해 알 수 있게, 안내를 포함하여야 한다는 의미.

  • 예를 들어, getAccountBalance로 계좌에 금액을 받아왔을때, 그 이후에 할 수 있는 작업들 (depositMoney, withdrawMoney) 에 대한 링크 정보도 같이 제공한다.

• 장점

  • 클라이언트에게 영향을 미치지 않고, URI 체계 변경 가능. 즉, API 업데이트시 유연하게 변경 가능

  • API를 사용하는 다른 개발자들에게 더 나은 개발 경험을 제공

• URI 생성을 위해 HATEOAS에서 제공되는 3가지 추상화

  • RepresentationModel

  • Link

  • WebMvcLinkBuilder

• 모델 4 가지

  • RepresentationModel

  • CollectionModel

  • EntityModel

  • PagedModel

• 용어

  • Resource: API로 부터 넘어온 링크 정보를 포함한 정보를 포괄하여 리소스라고 칭한다.

종속성 추가

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

스프링 부트 아닐시

<dependency>
    <groupId>org.springframework.hateoas</groupId>
    <artifactId>spring-hateoas</artifactId>
    <version>1.4.1</version>
</dependency>
<dependency>
    <groupId>org.springframework.plugin</groupId>
    <artifactId>spring-plugin-core</artifactId>
    <version>1.2.0.RELEASE</version>
</dependency>

실습

• linkTo()와 methodOn()는 hateoas 라이브러리에서 제공한다

• CollectionModel은 HAL 리턴 타입을 준수한다

// 사용될 주문, 고객 객체

public class Order extends RepresentationModel<Order> {
    private String orderId;
    private double price;
    private int quantity;
		//...
}

public class Customer extends RepresentationModel<Customer> {
    private String customerId;
    private String customerName;
    private String companyName;
    private Map<String, Order> orders;
 		//.. 
}

package com.baeldung.web.controller;

import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.linkTo;
import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.methodOn;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.hateoas.Link;
import org.springframework.hateoas.CollectionModel;
import org.springframework.hateoas.config.EnableHypermediaSupport;
import org.springframework.hateoas.config.EnableHypermediaSupport.HypermediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.baeldung.persistence.model.Customer;
import com.baeldung.persistence.model.Order;
import com.baeldung.services.CustomerService;
import com.baeldung.services.OrderService;

@RestController
@RequestMapping(value = "/customers")
@EnableHypermediaSupport(type = HypermediaType.HAL)
// HAL = 응답 메시지에 부가 정보들을 담아서 제공하는 방식 중 하나
public class CustomerController {
    @Autowired
    private CustomerService customerService;

    @Autowired
    private OrderService orderService;
  
  	@GetMapping("/{customerId}/{orderId}")
    public Order getOrderById(@PathVariable final String customerId, @PathVariable final String orderId) {
        return orderService.getOrderByIdForCustomer(customerId, orderId);
    }
    
    /**
    * 특정 고객의 모든 주문을 가져온다. 
    * 각 주문들에 포함된 상품 정보를 볼 것에 대비해 위 getOrderById 엔드포인트로 들어가는 링크를 제공한다.
    */
    @GetMapping(value = "/{customerId}/orders", produces = { "application/hal+json" })
    public CollectionModel<Order> getOrdersForCustomer(@PathVariable final String customerId) {
        final List<Order> orders = orderService.getAllOrdersForCustomer(customerId);
        for (final Order order : orders) {
             // 이 컨트롤러 안에 있는 getOrderById 엔드포인트의 링크를 생성
            final Link selfLink = linkTo(methodOn(CustomerController.class)
              .getOrderById(customerId, order.getOrderId())) 
              .withSelfRel();
            // 각 주문을 찾아오는 링크 더하기
            order.add(selfLink);
        }

        Link link = linkTo(methodOn(CustomerController.class)
                             .getOrdersForCustomer(customerId))
                              .withSelfRel();
        CollectionModel<Order> result = CollectionModel.of(orders, link);
        return result;
    }
  
    @GetMapping("/{customerId}")
    public Customer getCustomerById(@PathVariable final String customerId) {
        return customerService.getCustomerDetail(customerId);
    }

    /**
    * 모든 고객을 가져온다.
    * 각 고객들에 대한 API 링크와 고객들의 주문들을 볼 수 있는 링크 2개를 추가한다.
    */
    @GetMapping(produces = { "application/hal+json" })
    public CollectionModel<Customer> getAllCustomers() {
        final List<Customer> allCustomers = customerService.allCustomers();

        for (final Customer customer : allCustomers) {
            String customerId = customer.getCustomerId();
            Link selfLink = linkTo(CustomerController.class)
                                  .slash(customerId) // 위 getCustomerById() 엔드포인트 사용
                                  .withSelfRel();
            customer.add(selfLink);
          	
            // 주문이 1개라도 있다면, 링크 추가
            if (orderService.getAllOrdersForCustomer(customerId).size() > 0) {
                final Link ordersLink = linkTo(methodOn(CustomerController.class)
                                               .getOrdersForCustomer(customerId))
                    .withRel("allOrders");
                customer.add(ordersLink);
            }
        }

        Link link = linkTo(CustomerController.class).withSelfRel();
        CollectionModel<Customer> result = CollectionModel.of(allCustomers, link);
        return result;
    }
}

응답 결과

위 API의 getAllCustomers() 를 호출했을때 응답

{
  "_embedded": {
    "customerList": [{
        "customerId": "10A",
        "customerName": "Jane",
        "companyName": "ABC Company",
        "_links": {
          "self": {
            "href": "http://localhost:8080/spring-security-rest/api/customers/10A"
          },
          "allOrders": {
            "href": "http://localhost:8080/spring-security-rest/api/customers/10A/orders"
          }
        }
      },{
        "customerId": "20B",
        "customerName": "Bob",
        "companyName": "XYZ Company",
        "_links": {
          "self": {
            "href": "http://localhost:8080/spring-security-rest/api/customers/20B"
          },
          "allOrders": {
            "href": "http://localhost:8080/spring-security-rest/api/customers/20B/orders"
          }
        }
      },{
        "customerId": "30C",
        "customerName": "Tim",
        "companyName": "CKV Company",
        "_links": {
          "self": {
            "href": "http://localhost:8080/spring-security-rest/api/customers/30C"
          }
        }
      }]
  },
  "_links": {
    "self": {m
      "href": "http://localhost:8080/spring-security-rest/api/customers"
    }
  }
}

API의 getOrdersForCustomer() 를 사용했을때 응답

{
  "_embedded": {
    "orderList": [{
        "orderId": "001A",
        "price": 150,
        "quantity": 25,
        "_links": {
          "self": {
            "href": "http://localhost:8080/spring-security-rest/api/customers/10A/001A"
          }
        }
      },{
        "orderId": "002A",
        "price": 250,
        "quantity": 15,
        "_links": {
          "self": {
            "href": "http://localhost:8080/spring-security-rest/api/customers/10A/002A"
          }
        }
      }]
  },
  "_links": {
    "self": {
      "href": "http://localhost:8080/spring-security-rest/api/customers/10A/orders"
    }
  }
}

유투브 자료

HATEOAS를 이용해, 어떻게 API를 유연하게 만들수 있는지 보여준다.

기존 클래스를 교체하다가

참고자료

• https://www.baeldung.com/spring-hateoas-tutorial