Spring HATEOAS를 이용한 RESTful API 개발 방법

Spring HATEOAS는 RESTful API를 개발할 때 많은 도움을 주는 라이브러리 중 하나이다. 이번 글에서는 Spring HATEOAS를 이용하여 RESTful API를 개발하는 방법에 대해 알아보겠다.

Spring HATEOAS란 무엇인가?

Spring HATEOAS는 RESTful API에 Hypermedia를 적용하기 위해 개발된 라이브러리이다. 이 라이브러리를 이용하면 Hypermedia를 통해 API 사용자가 자원과 자원 간의 관계를 쉽게 파악할 수 있게 된다. 또한, 이 라이브러리를 이용하면 Link나 Resource와 같은 HATEOAS 관련 클래스들을 쉽게 생성하고 조작할 수 있게 된다.

Spring HATEOAS를 이용한 RESTful API란?

Spring HATEOAS를 이용하여 개발한 RESTful API는 Hypermedia를 적용한 API이다. 이렇게 만들면 API 사용자가 자원 간의 관계를 쉽게 파악할 수 있게 된다. 예를 들어, 게시판 API에서 게시글과 댓글 간의 관계를 파악하는 것이 쉬워진다. 즉, API 사용자가 원하는 자원을 보다 쉽게 찾을 수 있게 되는 것이다.

Spring HATEOAS를 이용한 RESTful API 개발환경 구성

Spring HATEOAS를 이용한 RESTful API를 개발하기 위해서는 Spring Boot, Spring Web, Spring Data JPA와 같은 Spring 기반 기술들이 필요하다. 또한, Spring HATEOAS 라이브러리를 의존성으로 추가해야 한다. 아래는 Gradle을 이용하여 의존성을 추가하는 예제이다.

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.hateoas:spring-hateoas:1.0.3.RELEASE'
}

Spring HATEOAS를 이용한 RESTful API 개발 실습하기

이제 Spring HATEOAS를 이용하여 RESTful API를 개발해보자. 예제로는 게시글과 댓글을 다루는 API를 만들어보겠다. 먼저, 게시글과 댓글에 대한 Model 클래스를 작성한다.

@Entity
public class Post {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String title;

    private String content;

    // 게시글과 댓글 간의 관계
    @OneToMany(mappedBy = "post")
    private List comments;
}

@Entity
public class Comment {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String content;

    // 게시글과 댓글 간의 관계
    @ManyToOne
    @JoinColumn(name = "post_id")
    private Post post;
}

다음으로는 Controller 클래스를 작성한다. 이때, Spring HATEOAS에서 제공하는 Resource 클래스를 이용하여 API의 응답을 생성할 수 있다. Resource 클래스는 Hypermedia를 적용한 API에서 많이 사용되는 클래스 중 하나이다.

@RestController
@RequestMapping("/posts")
public class PostController {
    private final PostRepository postRepository;
    private final CommentRepository commentRepository;
    private final PostAssembler postAssembler;

    @GetMapping
    public CollectionModel getPosts() {
        List posts = postRepository.findAll();
        List postResources = posts.stream()
                .map(postAssembler::toModel)
                .collect(Collectors.toList());
        return new CollectionModel(postResources);
    }

    @GetMapping("/{id}")
    public PostResource getPost(@PathVariable Long id) {
        Post post = postRepository.findById(id).orElseThrow(() -> new ResourceNotFoundException("Post not found with id " + id));
        return postAssembler.toModel(post);
    }

    @PostMapping
    public ResponseEntity createPost(@RequestBody Post post) {
        Post savedPost = postRepository.save(post);
        PostResource postResource = postAssembler.toModel(savedPost);
        return ResponseEntity.created(postResource.getRequiredLink(IanaLinkRelations.SELF).toUri()).body(postResource);
    }

    @PostMapping("/{id}/comments")
    public ResponseEntity createComment(@PathVariable Long id, @RequestBody Comment comment) {
        Post post = postRepository.findById(id).orElseThrow(() -> new ResourceNotFoundException("Post not found with id " + id));
        comment.setPost(post);
        Comment savedComment = commentRepository.save(comment);
        CommentResource commentResource = commentAssembler.toModel(savedComment);
        return ResponseEntity.created(commentResource.getRequiredLink(IanaLinkRelations.SELF).toUri()).body(commentResource);
    }
}

마지막으로는 Assembler 클래스를 작성한다. Assembler 클래스는 Model 클래스를 Resource 클래스로 변환하는 역할을 한다.

@Component
public class PostAssembler implements RepresentationModelAssembler {
    private final CommentAssembler commentAssembler;

    public PostAssembler(CommentAssembler commentAssembler) {
        this.commentAssembler = commentAssembler;
    }

    @Override
    public PostResource toModel(Post post) {
        PostResource postResource = new PostResource(post,
                linkTo(methodOn(PostController.class).getPost(post.getId())).withSelfRel(),
                linkTo(methodOn(PostController.class).getPosts()).withRel(IanaLinkRelations.COLLECTION));
        List commentResources = post.getComments().stream()
                .map(commentAssembler::toModel)
                .collect(Collectors.toList());
        postResource.add(commentResources);
        return postResource;
    }
}

이제 RESTful API를 실행하면 Hypermedia를 적용한 API를 만들 수 있다.

Spring HATEOAS를 이용하여 RESTful API를 개발하는 방법을 알아보았다. Spring HATEOAS를 이용하면 API 사용자가 자원 간의 관계를 쉽게 파악할 수 있게 된다. 이를 통해 API 사용자가 원하는 자원을 쉽게 찾을 수 있게 되며, 유지보수 측면에서도 이점을 얻을 수 있다.

Reference : Spring HATEOAS를 이용한 RESTful API 개발 방법