[Spring] Spring Boot로 간단한 API 만들기 (Hello REST API)

백엔드 개발에 주로 사용되는 Spring 프레임워크를 사용하여 간단한 Hello REST API를 만들어 보려고 합니다

REST API는 무엇이고 기본 동작 원리에 대해 정리하려고 합니다

REST (Representational State Transfer)

자원을 URI로 구분하고 HTTP Method를 활용하여 CRUD를 수행하는 아키텍처 스타일입니다

즉 어떤 자원(Resource)에 대해 무슨 행동(Method)을 할지 조합하여 API 설계하는 방식

REST API 의 특징

- 자원(Resource): /users, /blog/1 처럼 URI로 표현

- 행위(Method): GET,POST,PUT,PATCH,DELETE 같은 HTTP Method 사용

- 표현(Representation): JSON,XML 등으로 자원을 주고받음

HTTP Method와 예시

1. GET → 조회

서버에 있는 자원을 가져올 때 사용합니다

ex) GET /users/1 (id가 1인 유저 정보 조회)

 

2. POST → 생성

새로운 자원을 생성할 때 사용합니다

ex) POST /users (새로운 유저 등록)

 

3. PUT → 수정

자원의 전체 데이터를 교체할 때 사용합니다

ex) PUT /user/1 (id가 1인 유저 정보를 요청 본문 내용으로 수정)

 

4. PATCH → 부분 수정

자원의 일부 속성만 변경할 때 사용합니다

ex) PATCH /users/1 (id가 1인 유저의 닉네임만 수정)

 

5. DELETE → 삭제

자원을 제거할 때 사용합니다

ex) DELETE /users/1 (id가 1인 유저를 삭제) 

 

REST API 어디까지나 규약일 뿐이라 각 팀 상황에 맞춰 유연하게 변형하여 사용하게 되는 거 같아요

따라서 API 명세서를 작성할 때는 백엔드와 프런트엔드가 서로 협의하면서작성하는 게 되게 중요하다고 생각합니다

 

예를 들어서 엔드포인트 네이밍은 어떻게 정할 것인지 단수/복수?, 응답 형식은?, 예외는 어떻게 날려줄지

이러한 내용이 사전에 협의되지 않은 상태에서 프로젝트를 진행하게 되면 계속해서 직접적으로 백엔드 파트에 물어보게 되기 때문에 사전에 미리 설계를 잘하는 게 좋을 거 같습니다

 

미리 상의를 통해서 팀 컨벤션을 만들고 지켜서 프로젝트를 진행한다면 불필요한 커뮤니케이션을 줄일 수 있지 않을까 생각합니다

Spring Boot REST API 프로젝트 생성

IntelliJ IDEA Ultimate의 Spring Boot 프로젝트 생성 도구를 사용하여 프로젝트를 생성

프로젝트 설정

Name: HelloProject
Language: Java
JDK: 21

Spring dependency

- Spring Web

 

현재는 API 개발만 하기 때문에 dependency는 Spring Web만 추가하겠습니다

build.gradle

plugins {
    java
    id("org.springframework.boot") version "3.5.5"
    id("io.spring.dependency-management") version "1.1.7"
}

group = "com.tuioe"
version = "0.0.1-SNAPSHOT"
description = "HelloProject"

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

tasks.withType<Test> {
    useJUnitPlatform()
}

프로젝트 패키지 구조

간단하게 controller 패키지를 만들고 그 안에 HelloController 클래스를 생성해 줍니다

src
 └─ main
     └─ java
         └─ com.tuioe.helloproject
             └─ controller
                └─ HelloController.java

HelloController

package com.tuioe.helloproject.controller;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/hello")
public class HelloController {

    // GET - 조회
    @GetMapping("/{id}")
    public ResponseEntity<String> getHello(@PathVariable("id") Long id) {
        return ResponseEntity.ok("GET 요청 - id: " + id);
    }

    // POST - 생성
    @PostMapping
    public ResponseEntity<String> createHello(@RequestBody String body) {
        return ResponseEntity.ok("POST 요청 - body: " + body);
    }

    // PUT - 전체 수정
    @PutMapping("/{id}")
    public ResponseEntity<String> updateHello(@PathVariable("id") Long id,
                                              @RequestBody String body) {
        return ResponseEntity.ok("PUT 요청 - id: " + id + ", body: " + body);
    }

    // PATCH - 부분 수정
    @PatchMapping("/{id}")
    public ResponseEntity<String> patchHello(@PathVariable("id") Long id,
                                             @RequestBody String body) {
        return ResponseEntity.ok("PATCH 요청 - id: " + id + ", body: " + body);
    }

    // DELETE - 삭제
    @DeleteMapping("/{id}")
    public ResponseEntity<String> deleteHello(@PathVariable("id") Long id) {
        return ResponseEntity.ok("DELETE 요청 - id: " + id);
    }
}

간단하게 컨트롤러를 생성하여 각각 CRUD 기능을 담당하는 API를 만들었습니다

 

1. @RestController

@Controller + @ResponseBody의 합성 어노테이션으로 컨트롤러가 반환하는 값을 뷰(View) 형태가 아닌 HTTP 응답 Body에 직접 담아 반환하도록 하며 REST API 개발에 주로 사용됩니다 

 

2. @RequestMapping("/hello")

공통 URL prefix를 지정하는 어노테이션으로 클래스 위에 정의하면 하위 메서드들의 기본 URI 경로가 ("")에 작성한 문자로 시작하도록 지정합니다 같은 도메인(자원)에 속한 API들을 한 컨트롤러에서 관리할 때 사용하면 편리합니다

 

예를 들어 게시판을 개발한다고 했을 때 게시글,댓글,유저,좋아요 등 여러 가지 도메인이 있다면 하나의 도메인마다 컨트롤러를 1개씩 두고 클래스 상단에 URI를 정의하는 어노테이션으로 관리하게 되면 각 API를 추가할 때 경로를 반복적으로 작성할 필요가 없습니다

 

3. ResponseEntity<T>

Spring에서 제공하는 HTTP 응답 객체로 응답 상태 코드 + 헤더 + 바디를 모두 제어할 수 있는 클래스입니다

주로 REST API 응답의 세부 내용을 추가하여 반환하며 컨트롤하기 위해서 사용합니다

 

또한 제네릭을 활용하여 다양한 타입(String,DTO)의 응답을 안전하게 반환하도록 할 수 있습니다

 

반환 타입은 사용자가 직접 지정하여 사용할 수 있으며 String 타입이나 직접 DTO 클래스를 정의하여 반환하도록 지정하여 선언한 타입을 어기면 컴파일 에러 발생으로 타입 안정성을 보장합니다 주로 DTO 클래스를 만들어서 사용합니다

 

다음과 같이 사용할수 있습니다

@GetMapping("/user")
public ResponseEntity<UserDto> user() {
    return ResponseEntity.ok(new UserDto(1L, "tuioe"));
}

API 테스트

 

PostMan으로 테스트한 결과 잘 반환하는 걸 볼 수 있습니다