Springboot에서 HATEOAS 기반 RESTful API 개발하기

HATEOAS는 Hypermedia as the Engine of Application State의 약자이며, 웹 애플리케이션의 상태 값을 하이퍼미디어로 전달하는 방법을 말합니다. 하이퍼미디어는 텍스트, 음성, 영상 등 노드와 링크로 구성한 네트워크를 말합니다. 우리는 웹 사이트에서 정보를 탐색할 때, 문서에 연결된 하이퍼링크를 통하여 또 다른 웹 사이트에서 정보를 얻습니다. 책과 달리, 웹 문서의 내용은 비선형적으로 이루어져 있고, 정보를 제공하는 매체가 웹 문서마다 모두 연결되어 있으므로, 이를 하이퍼미디어라고 합니다. HATEAOS는 하이퍼미디어 기반으로 상태를 전달하는 방법이므로, 클라이언트는 서버에게 요청할 정보를 알지 못하여도, 서버로부터 요청하는 방법을 하이퍼미디어를 링크 형태로 제공받습니다.

이번 포스팅에서는 Springboot에서 HATEOAS 기반으로 응답이 가능한 RESTful API를 개발하는 방법에 대해 알아보겠습니다.

HATEOAS REST API 작성용 프로젝트 다운로드

https://start.spring.io/ 에서 Spring HATEOAS 디펜던시를 추가한 뒤 프로젝트를 다운로드합니다.

Spring HATEOAS 예제용 프로젝트 다운로드

다운로드된 프로젝트에서 build.gradle 파일을 열어보면 HATEOAS 디펜던시가 추가된 것을 확인할 수 있습니다.

implementation 'org.springframework.boot:spring-boot-starter-hateoas'

HATEOAS REST API 작성하기

/greeting GET URL 요청에 대해 JSON으로 응답하고, 옵션으로 name 파라미터를 받을 수 있는 애플리케이션을 만들어 보겠습니다.

package com.example.demo;

import org.springframework.hateoas.RepresentationModel;

import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;

public class Greeting extends RepresentationModel<Greeting> {

    private final String content;

    @JsonCreator
    public Greeting(@JsonProperty("content") String content) {
        this.content = content;
    }

    public String getContent() {
        return content;
    }
}

Greeting 클래스는 RepresentationModel<Greeting>을 상속받습니다. 상속받은 클래스를 활용해, /greeting 요청에 대한 응답을 하이퍼미디어로 제공할 수 있습니다. @JsonCreator는 객체가 JSON으로 직렬화 또는 역직렬화될 때, 사용되는 생성자를 지정해주는 어노테이션이고, @JsonProperty는 JSON의 Key 값을 변수로 매핑해주는 어노테이션입니다.

아래 클래스는 /greeting GET 요청을 처리하는 컨트롤러입니다.

package com.example.demo;

import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.*;

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;

@RestController
public class GreetingController {

    private static final String TEMPLATE = "Hello, %s!";

    @RequestMapping("/greeting")
    public HttpEntity<Greeting> greeting(
            @RequestParam(value = "name", defaultValue = "World") String name) {

        Greeting greeting = new Greeting(String.format(TEMPLATE, name));
        greeting.add(linkTo(methodOn(GreetingController.class).greeting(name)).withSelfRel());

        return new ResponseEntity<>(greeting, HttpStatus.OK);
    }
}

linkTo(), methodOn() 그리고 withSelfRel()을 이용하여 /greeting GET 요청에 따른 하이퍼미디어가 생성됩니다. /greeting 요청 처리를 위해 사용된 @RequestParam의 defaultValue 그리고 name 변수를 옵션으로 줄 수 있다는 정보는 HATEOAS를 통해 하이퍼미디어를 통해 링크로 생성됩니다. 즉, 클라이언트는 해당 URL 요청 방법을 서버로부터 손쉽게 얻을 수 있습니다.

클래스 작성을 마치고 스프링 부트 애플리케이션을 실행하여, /greeting URL에 접속하면, 클라이언트는 _links 속성을 제공받을 수 있습니다.

http://localhost:8080/greeting

{
    "content": "Hello, World!",
    "_links": {
        "self": {
       	 "href": "http://localhost:8080/greeting?name=World"
        }
    }
}

지금까지 Springboot에서 HATEOAS 기반 RESTful API를 만드는 방법에 대해 알아보았습니다.