[📰 위클리페이퍼] 웹 API 발전과정 & RestController

📌 API란?

🧐 인터페이스로서의 API

API는 "Application Programming Interface"의 약자로, 서로 다른 두 프로그램이 서로 대화할 수 있게 해주는 언어이자 명세서

💁 API의 역할과 필요성

• 기능 노출
  : 외부에 기능을 제공하되, 내부 로직은 숨김
• 시스템 경계 관리
  : 모듈 간 결합도를 낮추고, 구조적 독립성 확보
• 안정성 보장
  : 내부가 바뀌어도 외부에 영향 없음
• 협업 수단
  : API 명세서가 팀 간 약속이자 계약서 역할
• 재사용성 강화
  : 기능 단위로 재사용 가능

💻 웹 API의 특징

🔍 네트워크 기반 통신

웹 API는 클라이언트와 서버가 네트워크를 통해 데이터를 주고 받는 구조를 기반으로 함

GET /api/products/1 HTTP/1.1
Host: example.com
Accept: application/json

장점

• URL만 알면 접근 가능
• 브라우저, 모바일 앱, 외부 서비스 등 다양한 클라이언트에서 호출 가능
• 방화벽이나 인프라 제약이 적음 (HTTP 80/443 포트 사용)

🔍 플랫폼 독립성

웹 API는 특정 OS나 언어에 의존하지 않고, 표준화된 HTTP 요청과 JSON/XML 등의 포맷만 지키면 어떤 플랫폼에서든 접근이 가능함

🔍 분산 시스템에서의 역할

대규모 시스템에서는 각 기능을 담당하는 여러 개의 독립적인 마이크로서비스가 존재
-> 이들은 각자의 API를 통해 서로 데이터를 주고 받으며 동작함

ex) 주문 서비스와 상품 서비스가 분리되어 있음

[주문 서비스] --(HTTP API)--> [상품 서비스] --(HTTP API)--> [회원 서비스]

🔍 HTTP 프로토콜 활용의 장점

📌 무상태성 (Statelessness)

• 서버는 클라이언트의 이전 요청 정보를 저장하지 않음
• 각 요청은 독립적이며, 필요한 모든 정보를 요청 안에 포함해야 함

📌 비연결성 (Connectionless)

• HTTP는 요청-응답 후 연결을 끊음
• 지속적인 연결을 유지하지 않아 리소스 낭비를 줄임
  👉 서버는 많은 클라이언트 요청을 효율적으로 처리할 수 있음

🧐 SOAP?

SOAP(Simple Object Access Protocol)은 HTTP, SMTP 등의 프로토콜 위에서 XML 형식의 메시지를 주고 받는 방식의 API 통신 프로토콜
-> 주로 2000년대 초반 엔터프라이즈 시스템에서 표준으로 자리잡으며 대규모 시스템 간 연동에 사용됨

SOAP을 사용하게 된 이유
👉 플랫폼과 언어에 독립적인 통신 규약이 필요해졌기 때문

🔍 SOAP의 구조 이해

SOAP 메시지는 크게 Envelope, Header, Body 세 부분으로 구성되며, 각 요소는 XML로 구성되어 있어 엄격한 구조와 명확한 명세를 따름

<soapenv:Envelope xmlns:soapenv="<http://schemas.xmlsoap.org/soap/envelope/>">
   <soapenv:Header/>
   <soapenv:Body>
      <getUser>
         <id>1</id>
      </getUser>
   </soapenv:Body>
</soapenv:Envelope>

• Envelope : SOAP 메시지의 루트 요소, 모든 메시지는 이 안에 포함됨
• Header : 인증, 트랜잭션 등의 메타 정보를 담는 공간(선택적)
• Body : 실제 호출하려는 메서드 정보와 파라미터가 들어감

🔍 SOAP의 주요 특징

• 계약 기반
  : WSDL(웹 서비스 기술 명세)을 통해 서비스 정의 -> 클라이언트가 자동으로 인터페이스 생성
• 엄격한 스키마 검증
  : XSD 기반 스키마를 따름, 파라미터나 리턴 값의 구조가 명확하게 정의됨
• 전송 프로토콜 유연성
  : HTTP 외에도 SMTP, FTP 등 다양한 프로토콜에서 동작 가능
• 보안 및 신뢰성
  : WS-Security, WS-ReliableMessaging 등 다양한 확장 기능 제공
• 트랜잭션 보장
  : SOAP 메시지 내부에서 ACID 트랜잭션 관리 가능

👍 SOAP의 장점

• 강력한 표준화
  보안(WS-Security), 트랜잭션, 신뢰성 보장
• 기업 환경에 적합
  금융, 공공, 대규모 시스템에서 안정성 중시
• 명확한 계약(WSDL)
  인터페이스가 엄격해 협업에 유리

👎 SOAP의 한계

❌ XML 기반이라 메시지가 무겁고 복잡
❌ 구현과 디버깅 난이도가 높음
❌ 웹 환경(브라우저, 모바일)에 부적합
❌ 단순한 CRUD 작업에도 과한 설계

👉 “안정적이지만 너무 무겁다”는 평가를 받게 됨

💻 RESTful API의 부상

🧐 REST란?

REST(Representational State Transfer)는 2000년에 Roy Fielding이 정의한 웹 서비스 구조의 이름으로, 간단한 구조로 도움을 주는 API 스킬을 합리적으로 제공하기 때문에 일반적인 시스템에서 가장 많이 사용됨

👉 REST는 프로토콜이 아니라 아키텍처 스타일

💁 REST의 기본 조건

• Client-Server 구조
  : UI가 바로 변경 되는 것을 막고, 규칙적 분리
• Stateless(무상화)
  : 각 호출은 반복되는 정보와 문맥을 가지고 있어야 함
• Cacheable
  : 이전 결과를 개발자가 지정할 수 있음
• Layered System
  : 각 계층은 사용자가 다른 계층이라도 알 필요가 없음
• Uniform Interface
  : URI, HTTP method를 가지고 한가지 클릭을 통으로 간단히 건너주게 한다

🧐 SOAP -> REST로 전환된 이유

👉 웹, 모바일 시대에는 REST가 훨씬 효율적이었기 때문에 대부분의 웹 API가 REST 기반으로 전환되었음

💁 REST의 장단점

👍 REST의 장점

• 가볍고 직관적인 구조
• 빠른 개발 및 유지보수
• 프론트엔드/모바일과 궁합이 좋음
• HTTP 캐시 활용 가능

👎 REST의 단점

• 공식 표준이 없어 설계 품질 편차 발생
• 보안/트랜잭션을 직접 설계해야 함
• 복잡한 비즈니스 규칙 표현에는 한계

---

📌 @RestController

🧐 RestController?

@Restcontroller = @Controller + @ResponseBody
Spring MVC에서 일반적으로 사용하는 @Controller는 요청에 대해 HTML View 템플릿을 반환하는데 사용됨. But REST API 개발에서는 JSON, XML, 파일 등 실제 데이터 자체를 반환해야 하므로 @RestController 사용

@RestController
public class HelloRestController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello, JSON!"; // View가 아닌 HTTP 본문에 그대로 응답됨
    }
}

• @RestController는 클래스 단위에 적용되며, 내부 모든 메서드는 @ResponseBody 효과를 가짐
• ViewResolver를 거치지 않고 HttpMessageConverter를 통해 응답 데이터로 직렬화됨
• 기본 출력 형식은 application/json이며, Accept 헤더로 명시 가능

💻 @RestController 동작 과정

1️⃣ 클라이언트 -> DispatcherServlet (Front Controller)

1. 클라이언트 HTTP 요청을 보냄

POST /api/users
Content-Type: application/json

2. 요청은 Spring MVC의 진입점인 DispatcerServlet이 받아서 처리함

2️⃣ HandlerMapping - 어떤 컨트롤러가 처리할지 결정

3. DispatcherServlet은 HandlerMapping들에게 요청을 위임함

• URL
• HTTP Method(GET, POST 등)
• @ResquestMapping, @GetMapping 등의 정보

4. 해당 요청을 처리할 컨트롤러 메서드를 찾음

@PostMapping("/api/users")
public UserResponse create(@RequestBody UserRequest request)

3️⃣ HandlerAdapter - 컨트롤러 메서드 실행 준비

5. 찾은 컨트롤러를 직접 실행하지 않고, HandlerAdapter가 실행을 담당함
   👉 스프링은 다양한 타입의 핸들러를 지원해야 하므로 중간 어댑터 계층을 둠

4️⃣ HTTP 메시지 컨버터 (요청 바인딩 시점)

6. 컨트롤러 메서드를 호출하기 직전, HTTP 요청 바디 -> 자바 객체 변환이 필요함

public UserResponse create(
	@RequestBody UserRequest request
)

7. 여기서 HTTP Message Converter가 작동함

📌 역할

• HTTP Body(JSON, XML 등)를 Java 객체로 전환
• @RequestBody, @ResponseBody 처리의 핵심 컴포넌트

📌 동작 과정

• Content-Type 확인 (예: application/json)
• 이를 처리할 수 있는 컨버터 선택 (MappingJackson2HttpMessageConverter)
• JSON -> UserRequest 객체로 역직렬화

JSON

{
  "name": "kim",
  "age": 25
}

Java

new UserRequest("kim", 25)

5️⃣ Controller 메서드 실행

8. 변환된 파라미터를 가지고 컨트롤러 메서드 실행

UserResponse response = userService.create(request);

9. 비즈니스 로직 수행 (Service -> Repository)

6️⃣ HTTP 메시지 컨버터 (응답 변환 시점)

10. 컨트롤러가 객체를 반환

11. @RestController의 의미
    @Controller + @ResponseBody
    반환값을 View가 아니라 HTTP Body로 처리

12. 다시 HTTP Message Converter가 동작
    Java 객체 -> HTTP Response Body

📌 동작 과정

• Accept 헤더 확인 (예: application/json)
• 응답을 처리할 컨버터 선택
• UserResponse -> JSON 직렬화

7️⃣ DispatcherServlet -> 클라이언트 응답 반환

13. DispatcherServlet 이

• HTTP Status
• Headers
• Body

를 포함한 응답을 생성

14. 최종적으로 클라이언트에게 HTTP 응답 반환

🚀 정리

Spring Boot에서 @RestController 요청은 DispatcherServlet을 중심으로 HandlerMapping과 HandlerAdapter를 거쳐 처리되며, HTTP 메시지 컨버터는 컨트롤러 호출 전에는 요청 바디를 자바 객체로 변환하고, 호출 후에는 반환 객체를 HTTP 응답 바디로 직렬화하는 역할을 수행함