네이버 Tech Talk - 그런 REST API로 괜찮은가

 

📌 REST란 무엇인가?

 ~> REST(Representational State Transfer)는 분산 하이퍼미디어 시스템을 위한 아키텍처 스타일로, 웹의 독립적 진화를 보장하기 위한 6가지 제약 조건 존재한다.
  1. Client-Server: 클라이언트와 서버의 역할 분리
  2. Stateless: 서버는 클라이언트의 상태를 저장하지 않음
  3. Cacheable: 응답은 캐시 가능해야 함
  4. Uniform Interface: 일관된 인터페이스 제공
  5. Layered System: 계층화된 시스템 구조
  6. Code-on-Demand (Optional): 서버가 클라이언트로 코드를 전송할 수 있음
 

📌 REST의 핵심 - Uniform Interface

 ~> 이 발표에서는 특히 Uniform Interface의 2가지 세부 조건에 주목한다
  1. Self-descriptive Messages
   • 메시지 자체만으로 의미를 파악할 수 있어야 함
   • 요청/응답에는 메타정보(예: Content-Type, Link 등)가 포함되어야 함
  2. HATEOAS (Hypermedia as the Engine of Application State)
   • 클라이언트는 응답에 포함된 하이퍼링크를 통해 다음 행동을 유도받아야 함
   • 예: HTML에서 <a href="/edit">수정</a> 같은 역할
 

📌 REST를 지키기 어려운 이유

항목	흔한 웹 페이지	HTTP API
Protocol	HTTP	HTTP
커뮤니케이션	사람 ↔ 기계	기계 ↔ 기계
Media Type	HTML	JSON

 ~> REST의 본질을 이해하기 위해 먼저 HTML 기반의 “웹”과 JSON 기반의 “HTTP API”가 어떻게 다르냐를 비교한다.
 ~> REST는 HTML 기반 웹을 전제로 했지만, 현대 API는 JSON을 사용하고, 주체도 사람 ↔ 기계 에서 기계 ↔ 기계로 바뀌었다.
 

📌 HTML vs JSON - 왜 REST가 어려운가?

1. HTML은 REST에 잘 맞는다.
✅ Self-descriptive (자체 설명 메시지)
 ~> Content-Type: text/html 을 보고 HTML 문서임을 안다.
 ~> text/html은 IANA에 등록된 표준 media type이다.
 ~> 명세는 W3C HTML 명세에서 확인할 수 있다.
 ~> HTML 태그 <a>, <form> 등은 사용자가 어떤 행동을 할 수 있는지 자연스럽게 안내한다.
✅ HATEOAS (하이퍼미디어를 통한 상태 전이)
 ~> <a href="..."> 링크만으로 다음 행동을 유도할 수 있다.
 ~> 사용자(또는 브라우저)는 문서 안의 링크만 따라가면 된다.
 ~> 즉, 메시지만으로 상태 전이가 가능하다.
 
2. JSON은 REST에 적합하지 않다.
❌ Self-descriptive (자체 설명 메시지)
  ~> Content-Type: application/json이 명시돼 있으나, JSON 내부의 "id", "title"이 무엇을 의미하는지는 외부 문서 없이는 알 수 없다.
 ~> 명세는 있지만, 필드의 의미까지는 설명하지 않으므로, 사람이 해석해야 한다.
❌ HATEOAS (하이퍼미디어를 통한 상태 전이)
  ~> JSON 응답에는 "다음에 뭘 할 수 있는지"를 알려주는 링크가 없다.
  ~> /todos/1을 수정하려면, 클라이언트가 API 문서를 알고 있어야 한다.
  ~> 즉, 자기 기술이 아닌, 사전 지식에 의존한다.
 

📌 그래서 대부분의 REST API는 사실 "RESTful" 하지 않다.

위와 같이 REST의 본질적인 제약을 만족시키기 어렵기 때문에, 실무에서는 대부분의 JSON 기반 API가 실제로는 REST스럽지 않은 경우가 많다.
 
이유를 정리해 보자면
 1. JSON은 하이퍼미디어를 표현하기 어렵다.
   ~> HTML은 <a>, <form> 등으로 다음 행동을 자연스럽게 유도하지만, JSON은 기본적으로 데이터만 표현하고, 다음 행동에 대한 링크를 담지 않는다.
 2. 클라이언트는 하드코딩된 URL을 사용한다.
  ~> 링크가 메시지 안에 없기 때문에, 클라이언트가 사전에 경로(/todos/{id}/edit 등)를 알아야 동작 가능하다.
 3. API 문서가 없으면 사용이 불가능하다.
  ~> REST라면 메시지 자체만으로 사용법이 보여야 하지만, JSON은 필드명이 무엇을 의미하는지 설명하지 않기 때문에 Swagger 같은 문서를 참고해야 한다.
 • 개발 및 유지보수 비용이 높아진다.
  ~> Self-descriptive 또는 HATEOAS를 구현하려면 커스텀 미디어 타입, 링크 삽입, 명세 문서 관리 등 추가 구현과 표준화 작업이 필요하다.
 
그럼에도 왜 JSON을 쓰는가?

이유	설명
HTML은 사람을 위한 포맷	JSON은 기계 간 통신에 최적화
REST는 원래 '사람 ↔ 웹'에 초점	지금은 대부분 '기계 ↔ 기계' 통신 (HTTP API)
JSON은 가볍고 사용이 쉬움	하지만 REST 철학을 담기에는 정보가 부족함
실제로 HATEOAS 구현 부담이 큼	대부분 생략됨, 사실상 문서 기반 통신

 

📌 대안은? 더 정직하게 부르기

 • 모든 API를 REST API라고 부르지 말자. (즉, REST API라는 단어를 남용하지 말자.)
 • REST 제약을 따르지 못한다면 HTTP API 혹은 RPC-style API로 부르는 것이 정확하다.
 • REST는 단순한 URL 설계 방식이 아니라, "서버와 클라이언트의 독립적 진화를 보장하는 설계 철학"임을 기억하자.