Java 고급 네트워크

Java RESTful API 설계

Java RESTful API 설계 — 고급

RESTful API 설계

1. 도입 (왜 배워야 하는가)

RESTful API는 현대 웹 애플리케이션의 중요한 구성 요소입니다. 클라이언트와 서버 간의 통신을 효율적으로 관리할 수 있도록 해주며, 다양한 플랫폼 간의 데이터 전송을 가능하게 합니다. REST(Representational State Transfer)는 HTTP를 기반으로 하여 자원을 정의하고, 이 자원에 대한 행위를 명확하게 정의합니다.

이 토픽을 모르면 다음과 같은 문제가 발생할 수 있습니다:

클라이언트와 서버 간의 비효율적인 통신으로 인해 성능 저하가 발생할 수 있습니다.
API의 사용이 불명확해져서 다른 개발자들과의 협업이 어려워집니다.
보안 및 데이터 무결성을 보장하기 어려워져, 애플리케이션의 신뢰성이 떨어질 수 있습니다.

2. 핵심 개념 설명

RESTful API의 핵심 개념은 다음과 같습니다.

용어	설명
자원(Resource)	API에서 다루는 데이터의 단위입니다. 예를 들어, 사용자, 상품 등이 자원이 될 수 있습니다.
URI	자원의 위치를 나타내는 고유한 식별자입니다. 예: `/users/1`
HTTP 메서드	자원에 대한 행위를 정의합니다. 보통 GET, POST, PUT, DELETE가 사용됩니다.

이 개념들을 실생활의 비유로 설명하자면, "음식점"을 생각해 볼 수 있습니다. 음식점에서 "메뉴"가 자원이며, 각 요리의 이름(URI)이 있습니다. 손님이 "음식을 주문하다"는 것은 POST 메서드, "음식을 가져가다"는 GET 메서드, "음식을 수정하다"는 PUT 메서드, "음식을 취소하다"는 DELETE 메서드와 유사합니다.

3. 기본 코드 예제

아래는 Spring Boot를 사용하여 간단한 RESTful API를 구현하는 코드입니다.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

@SpringBootApplication
@RestController
@RequestMapping("/api/users")
public class UserApi {

    private List<String> users = new ArrayList<>();

    public static void main(String[] args) {
        SpringApplication.run(UserApi.class, args);
    }

    @GetMapping
    public List<String> getUsers() {
        return users; // 모든 사용자 목록을 반환
    }

    @PostMapping
    public String addUser(@RequestBody String user) {
        users.add(user); // 새로운 사용자를 추가
        return user + " added"; // 추가된 사용자 정보 반환
    }
}

실행 결과

GET /api/users 요청 시: [] (빈 리스트)
POST /api/users 요청 시: John added (새로운 사용자 추가)

코드 설명

@SpringBootApplication : Spring Boot 애플리케이션을 정의합니다.
@RestController : RESTful 웹 서비스를 제공하는 컨트롤러입니다.
@RequestMapping("/api/users") : /api/users URI로 들어오는 요청을 처리합니다.
getUsers() : GET 요청 시 모든 사용자 목록을 반환합니다.
addUser() : POST 요청 시 새로운 사용자를 추가합니다.

4. 실전 활용 예제

쇼핑몰에서 장바구니 구현하기

- 사용자가 상품을 장바구니에 추가할 때 POST 메서드를 사용하여 장바구니에 상품을 추가합니다.

@PostMapping("/cart")
public String addToCart(@RequestBody String product) {
    cart.add(product); // 장바구니에 상품 추가
    return product + " added to cart"; // 추가된 상품 정보 반환
}

게시판에서 댓글 작성하기

- 사용자가 게시글에 댓글을 작성할 때 POST 메서드를 사용합니다.

@PostMapping("/posts/{postId}/comments")
public String addComment(@PathVariable String postId, @RequestBody String comment) {
    comments.add(comment); // 해당 게시글에 댓글 추가
    return "Comment added to post " + postId; // 댓글 추가 완료 메시지
}

5. 흔한 실수와 주의사항

HTTP 메서드 혼동

- 잘못된 코드:

   @PostMapping("/users/{id}")
   public String deleteUser(@PathVariable String id) {
       // 사용자 삭제 코드
   }

- 올바른 코드:

   @DeleteMapping("/users/{id}")
   public String deleteUser(@PathVariable String id) {
       // 사용자 삭제 코드
   }

- 주의: DELETE 메서드를 사용하여 자원을 삭제하는 것이 중요합니다.

URI 설계 불일치

- 잘못된 URI: /api/users/add - 올바른 URI: /api/users (POST 메서드 사용) - 주의: 자원에 대한 행위를 URI로 표현하지 않고 HTTP 메서드로 표현해야 합니다.

6. 정리

RESTful API는 클라이언트와 서버 간의 효율적인 통신을 가능하게 합니다.
자원, URI, HTTP 메서드의 개념을 명확히 이해해야 합니다.
Spring Boot를 활용하여 간단한 RESTful API를 구현할 수 있습니다.
다음에 학습하면 좋은 주제: JWT를 이용한 인증 및 권한 관리, GraphQL API 설계.

학습