Spring Boot에서 REST API 설계 및 개발하기

1. REST API란 무엇인가?

REST(Representational State Transfer) API는 HTTP를 통해 클라이언트와 서버 간에 데이터를 주고받는 방식입니다. RESTful API는 자원을 URI로 식별하고, HTTP 메서드(GET, POST, PUT, DELETE 등)를 통해 자원을 조작합니다. REST API는 클라이언트-서버 구조, 무상태성, 캐시 처리 가능 등 몇 가지 중요한 특성을 가지고 있습니다.

RESTful API의 주요 특성:

1. 클라이언트-서버 구조: 클라이언트는 사용자 인터페이스를 담당하고, 서버는 데이터 처리와 저장을 담당합니다.
2. 무상태성(Stateless): 서버는 클라이언트의 상태를 저장하지 않으며, 각 요청은 독립적입니다.
3. 캐시 처리 가능(Cacheable): 클라이언트가 응답을 캐시할 수 있어 성능 향상에 도움이 됩니다.

---

2. Spring Boot로 REST API 설계하기

Spring Boot에서는 @RestController와 @RequestMapping, @GetMapping, @PostMapping, @PutMapping, @DeleteMapping과 같은 어노테이션을 사용해 REST API를 쉽게 설계할 수 있습니다.

2.1. 기본 REST API 설계

@RestController는 @Controller와 @ResponseBody가 결합된 어노테이션으로, JSON 형태로 응답을 반환합니다. 기본적인 GET API 예시를 살펴보겠습니다.

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        User user = userService.getUserById(id);
        if (user != null) {
            return ResponseEntity.ok(user);
        }
        return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
    }
}

• @GetMapping("/{id}"): GET 요청을 처리하고, URL의 {id}를 변수로 받습니다.
• ResponseEntity: HTTP 응답 상태 코드와 함께 데이터를 반환합니다.

2.2. POST API 설계

클라이언트에서 새로운 사용자 정보를 서버로 보내는 POST API를 설계해 보겠습니다.

@PostMapping
public ResponseEntity<User> createUser(@RequestBody User user) {
    User createdUser = userService.createUser(user);
    return ResponseEntity.status(HttpStatus.CREATED).body(createdUser);
}

• @RequestBody: 요청 본문에 포함된 JSON 데이터를 User 객체로 변환합니다.
• ResponseEntity.status(HttpStatus.CREATED): HTTP 상태 코드 201 Created로 응답을 반환합니다.

---

3. REST API 문서화

효율적인 REST API 설계를 위해 API 문서화는 매우 중요합니다. Spring Boot에서는 Swagger와 Spring REST Docs를 활용하여 API 문서를 자동으로 생성할 수 있습니다.

3.1. Swagger를 활용한 API 문서화

Swagger는 REST API의 명세서를 자동으로 생성하는 도구입니다. Spring Boot에서 Swagger를 사용하려면 springfox-swagger2와 springfox-swagger-ui 라이브러리를 추가해야 합니다.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Swagger를 활성화하려면, @EnableSwagger2 어노테이션을 추가하고 Docket 빈을 설정합니다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build();
    }
}

이제 http://localhost:8080/swagger-ui.html에서 자동으로 생성된 API 문서를 확인할 수 있습니다.

3.2. Spring REST Docs를 활용한 API 문서화

Spring REST Docs는 Swagger와 달리 Test 기반으로 API 문서를 작성할 수 있도록 도와줍니다. 예를 들어, API 테스트를 작성하고 그 결과를 바탕으로 문서를 생성할 수 있습니다.

<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <version>2.0.5</version>
    <scope>test</scope>
</dependency>

테스트에서 문서화를 적용하는 예시는 다음과 같습니다.

@RunWith(SpringRunner.class)
@WebMvcTest(UserController.class)
@AutoConfigureRestDocs(outputDir = "target/snippets")
public class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void testGetUser() throws Exception {
        mockMvc.perform(get("/api/users/{id}", 1))
                .andExpect(status().isOk())
                .andDo(document("get-user"));
    }
}

위 테스트 코드가 실행되면 target/snippets 디렉토리 안에 API 문서가 자동으로 생성됩니다.

---

4. REST API 보안

REST API는 외부와 데이터를 주고받기 때문에 보안이 매우 중요합니다. Spring Boot에서는 Spring Security를 활용해 API를 보호할 수 있습니다.

4.1. JWT 인증

JWT(Json Web Token)를 활용한 인증 방식을 사용하면, 클라이언트가 로그인한 후 토큰을 받아서 이후의 API 요청에 헤더로 포함시켜 인증을 진행할 수 있습니다.

public class JwtTokenProvider {
    private String secretKey = "your-secret-key";

    public String createToken(String username) {
        return Jwts.builder()
                .setSubject(username)
                .signWith(SignatureAlgorithm.HS256, secretKey)
                .compact();
    }

    public Claims getClaims(String token) {
        return Jwts.parser()
                .setSigningKey(secretKey)
                .parseClaimsJws(token)
                .getBody();
    }

    public boolean validateToken(String token) {
        try {
            Jwts.parser().setSigningKey(secretKey).parseClaimsJws(token);
            return true;
        } catch (JwtException e) {
            return false;
        }
    }
}

JWT를 사용하는 방식은 API 보안을 강화하고, 서버에 세션 정보를 저장하지 않기 때문에 무상태성을 유지할 수 있습니다.

---

✅ 정리

1. REST API 설계: Spring Boot에서는 @RestController와 @RequestMapping, @GetMapping, @PostMapping 등을 사용하여 API를 쉽게 설계할 수 있습니다.
2. Swagger를 사용한 API 문서화: Swagger를 활용하여 API 문서를 자동으로 생성하고 관리할 수 있습니다.
3. Spring Security: JWT를 활용하여 API의 인증과 인가를 관리할 수 있습니다.

REST API 설계와 개발은 웹 애플리케이션의 핵심입니다. 위 방법들을 잘 활용하면 효율적이고 보안성이 높은 RESTful API를 구축할 수 있습니다.