HATEOAS를 이용한 RESTful 서비스 구현

 

1. HATEOAS란 무엇인가?

RESTful 서비스 구현에서 흔히 언급되는 HATEOAS(Hypermedia As The Engine Of Application State)는 REST의 중요한 제약 조건 중 하나로, 클라이언트가 서버와의 상호작용을 동적이고 자율적으로 탐색할 수 있게 해주는 기법입니다.

HATEOAS의 핵심은 API의 응답에 상태 전환을 위한 링크를 포함시키는 것입니다. 이를 통해 클라이언트는 API의 전체 구조를 사전에 알지 못하더라도 필요한 리소스를 탐색하고 작업을 수행할 수 있습니다.

주요 특징

• 링크 중심 설계: 클라이언트는 서버가 제공하는 링크를 통해 다음 동작을 결정합니다.
• 자체 문서화: API 응답 자체에 가능한 동작과 경로를 설명하는 정보가 포함됩니다.
• 유연성: 클라이언트가 사전에 정의된 경로를 알 필요 없이 동적으로 서버와 상호작용할 수 있습니다.

---

2. HATEOAS를 활용해야 하는 이유

RESTful API는 보통 단순한 리소스 기반 설계로 시작합니다. 하지만 규모가 커지고 기능이 복잡해질수록 클라이언트와 서버 간의 결합도가 증가할 위험이 있습니다. HATEOAS는 이를 방지하며, 여러 이점을 제공합니다.

주요 이점

1. 클라이언트와 서버 간 결합도 감소
   • API 경로 변경 시 클라이언트를 수정하지 않아도 됩니다.
   • 링크 정보가 동적으로 제공되기 때문입니다.
2. 유연하고 확장 가능한 시스템
   • 새로운 리소스를 추가하거나 기존 리소스를 변경할 때 API의 유지보수가 쉬워집니다.
3. 상호작용성 개선
   • 클라이언트는 명시적으로 제공된 링크를 통해 서버와의 상태 전이를 수행하므로 명확한 API 동작이 가능합니다.

---

3. 스프링 부트에서 HATEOAS 구현하기

스프링 부트3는 HATEOAS 구현을 간단히 할 수 있는 강력한 도구와 라이브러리를 제공합니다. 이 중에서도 spring-boot-starter-hateoas는 HATEOAS를 적용하기 위한 주요 도구입니다.

프로젝트 설정

먼저, HATEOAS 구현을 위한 기본 설정을 추가합니다.

build.gradle 혹은 pom.xml에 의존성 추가

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

---

주요 클래스와 코드 구현

1) 리소스 모델 생성

HATEOAS에서는 RepresentationModel을 사용하여 리소스를 나타냅니다.

import org.springframework.hateoas.RepresentationModel;

public class Product extends RepresentationModel<Product> {
    private Long id;
    private String name;
    private Double price;

    // Getter, Setter
}

2) REST 컨트롤러 구현

HATEOAS 링크를 포함하여 리소스를 반환하는 컨트롤러를 작성합니다.

import org.springframework.hateoas.Link;
import org.springframework.hateoas.server.mvc.WebMvcLinkBuilder;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Arrays;
import java.util.List;

@RestController
@RequestMapping("/products")
public class ProductController {

    @GetMapping
    public List<Product> getAllProducts() {
        Product product1 = new Product();
        product1.setId(1L);
        product1.setName("Laptop");
        product1.setPrice(1500.00);

        Product product2 = new Product();
        product2.setId(2L);
        product2.setName("Smartphone");
        product2.setPrice(800.00);

        // HATEOAS 링크 추가
        Link selfLink1 = WebMvcLinkBuilder.linkTo(WebMvcLinkBuilder.methodOn(ProductController.class).getProductById(1L)).withSelfRel();
        Link selfLink2 = WebMvcLinkBuilder.linkTo(WebMvcLinkBuilder.methodOn(ProductController.class).getProductById(2L)).withSelfRel();

        product1.add(selfLink1);
        product2.add(selfLink2);

        return Arrays.asList(product1, product2);
    }

    @GetMapping("/{id}")
    public Product getProductById(Long id) {
        Product product = new Product();
        product.setId(id);
        product.setName("Sample Product");
        product.setPrice(500.00);

        Link selfLink = WebMvcLinkBuilder.linkTo(WebMvcLinkBuilder.methodOn(ProductController.class).getProductById(id)).withSelfRel();
        product.add(selfLink);

        return product;
    }
}

---

예시 실행 결과

1) GET /products 요청

[
  {
    "id": 1,
    "name": "Laptop",
    "price": 1500.00,
    "_links": {
      "self": {
        "href": "http://localhost:8080/products/1"
      }
    }
  },
  {
    "id": 2,
    "name": "Smartphone",
    "price": 800.00,
    "_links": {
      "self": {
        "href": "http://localhost:8080/products/2"
      }
    }
  }
]

2) GET /products/1 요청

{
  "id": 1,
  "name": "Laptop",
  "price": 1500.00,
  "_links": {
    "self": {
      "href": "http://localhost:8080/products/1"
    }
  }
}

---

4. 활용 사례

예제 1: 온라인 쇼핑몰 API

온라인 쇼핑몰에서 상품, 카테고리, 주문 등 여러 리소스 간 상태 전환을 안내하는 링크를 제공하여 클라이언트가 동적으로 탐색 가능하게 합니다.

예제 2: 금융 서비스

계좌 정보와 관련된 링크(예: 잔액 조회, 거래 내역 조회, 송금 링크)를 제공하여 사용자가 동적으로 기능을 활용하도록 합니다.

예제 3: 고객 관리 시스템

고객 프로필에 대한 링크(예: 수정, 삭제, 주문 내역 보기)를 포함하여 관리자가 쉽게 데이터를 탐색하고 관리할 수 있게 지원합니다.

---

5. 결론

HATEOAS는 RESTful API 설계에서 진정한 REST의 철학을 실현하는 중요한 요소입니다. 스프링 부트3를 활용하면 HATEOAS 구현이 훨씬 쉬워지며, 이를 통해 더 유연하고 확장 가능한 API를 구축할 수 있습니다. 이번 기회를 통해 HATEOAS를 프로젝트에 적용해보고 RESTful 서비스의 완성도를 높여보세요!