[Spring] 5. RESTful API

웹 브라우저, 모바일 앱, 다른 서버 등 다양한 클라이언트가 내 Spring 서버에 요청을 보낼 수 있다.
이때 서로 약속된 통신 규약이 필요한데 그것이 바로 ‘API (Application Programming Interface)’이다.

REST(Representational State Transfer) 란?

• 웹 API 를 설계하는 가장 대표적인 ‘아키텍처 스타일(Architectural Style)’
  
• 웹에 존재하는 모든 것을 ‘자원(Resource)’으로 보고, 각 자원에 고유한 ‘주소(URI)’를 부여하며, 정해진 ‘행위(HTTP Method)’를 통해 자원의 상태를 주고받는다.

---

REST의 3가지 핵심 구성 요소

1. 자원 (Resource)

• 의미 : API가 관리하는 모든 것. 웹에서 다루는 모든 데이터나 엔티티를 의미한다.
• 예시 : 사용자 정보, 게시글, 상품, 주문 등. 시스템의 ‘명사’에 해당한다.
• 표현 : 각 자원은 고유한 주소(URI, Uniform Resource Identifier)를 통해 식별된다.
  ex) /users/123, /products/456

2. 행위 (Verb)

• 의미 : 자원에 대해 수행하고 싶은 작업.
• 예시 : 조회, 생성, 수정, 삭제 등.

• 표현 : 이 행위들은 표준 HTTP 메서드를 통해 명시적으로 표현된다.

  HTTP Method	역할
  GET	자원 조회
  POST	자원 생성
  PUT	자원 전체 수정
  PATCH	자원 부분 수정
  DELETE	자원 삭제

3. 표현 (Representation)

• 의미 : 클라이언트와 서버가 자원의 상태를 주고받는 ‘표현 형태’.
• 예시 : 특정 사용자의 정보를 요청했을 때, 그 사용자의 상태는 JSON 또는 XML과 같은 형식으로 표현되어 전달된다.
• 특징 : 클라이언트와 서버는 HTTP 헤더(Content-Type, Accept)를 통해 어떤 표현 형태로 소통할지 약속한다. 현대 웹에서는 대부분 JSON을 사용한다.

---

‘RESTful’ 이란?

• API가 REST의 설계 원칙들을 잘 따라서 만들어졌을 때, 우리는 그 API를 ‘RESTful 하다’라고 말한다.
• RESTful API 설계의 핵심 원칙
  • “URI는 자원을 표현하는 데 집중하고, 행위는 HTTP 메서드에 위임한다.”
• URI에는 자원을 나타내는 명사만 포함하고, get, create, delete 같은 동사를 포함하지 않는 것이 좋다.

작업 내용	잘못된 예시 (Bad)	올바른 예시 (Good)
사용자 1번 조회	GET /getUser?id=1	GET /users/1
모든 사용자 조회	GET /getAllUsers	GET /users
사용자 생성	POST /createUser	POST /users
사용자 1번 수정	POST /updateUser	PUT /users/1
사용자 1번 삭제	GET /deleteUser?id=1	DELETE /users/1

이렇게 일관된 규칙으로 API를 설계하면, API의 기능을 예측하기 쉬워지고 사용성이 크게 향상된다.

---

스프링과 RESTful API

• 스프링 프레임워크는 @RestController 어노테이션을 통해 RESTful API를 매우 쉽고 편리하게 만들 수 있도록 지원한다.
• @RestController는 데이터(JSON 등) 자체를 반환하도록 설계되어 RESTful API 제작에 최적화되어 있다.

@RestController
public class UserController {

    // GET /users/1
    @GetMapping("/users/{id}")
    public User getUser(@PathVariable Long id) {
        // ... id로 사용자를 조회하는 로직 ...
        return new User("김스프링", "spring@example.com"); // 이 User 객체가 JSON으로 변환되어 응답
    }

    // POST /users
    @PostMapping("/users")
    public void createUser(@RequestBody User user) {
        // ... 전달받은 user 데이터로 사용자를 생성하는 로직 ...
    }
}