대부분의 RESTful API는 실제로 RESTful하지 않음

• Roy Fielding의 REST 원조 논문에서는 HTTP 메서드나 CRUD 중심의 API 사용을 명확히 규정하지 않으며, REST는 원래 하이퍼미디어 기반(HATEOAS) 시스템 설계를 강조함
• 많은 이들이 RESTful API라 부르는 것들은 중요한 REST 제약조건(특히 하이퍼미디어 사용)을 구현하지 않음
• 리소스는 단순 데이터 구조나 엔티티에 국한되지 않고, URI로 식별 가능한 모든 개념을 포함함
• Fielding의 6가지 규칙에 따르면, 하이퍼미디어 중심 탐색, 프로토콜 독립성, 미디어 타입 중시 등이 핵심임
• 현실적으로는 OpenAPI 등 문서화 도구 편의성 때문에 대부분의 API가 진정한 RESTful보다는 RPC 스타일에 가깝게 설계되는 경향이 많음

대부분의 RESTful API가 진정한 RESTful이 아닌 이유

• Roy Fielding의 대표 논문(2000) 은 REST(Representational State Transfer)를 네트워크 기반 소프트웨어 설계의 이상적 스타일로 제시하며, 웹의 성공을 뒷받침하는 원리로 설명함
• 논문에서는 HTTP 메서드 사용, CRUD 중심 설계를 필수로 규정하지 않으며, REST를 지향할 때 하이퍼미디어(HATEOAS) 기반 상태 전이, 보편적 인터페이스, 자원 중심의 상호작용이 핵심임을 강조함

하이퍼미디어(HATEOAS)와 REST의 오해

• Fielding은 하이퍼미디어 없는 API는 RESTful이 아니라고 명확히 지적함
  • "엔진이 하이퍼텍스트에 의해 구동되지 않으면 RESTful이 아님"
• HATEOAS란 클라이언트가 서버 응답에 내장된 링크를 따라 동적으로 행동을 탐색하는 방식임
• 단순히 HTTP/CRUD 인터페이스만 사용하는 것은 REST의 본질과 다름

REST의 흔한 오해

• REST는 CRUD라는 인식(실제로는 더 넓은 개념)
• 리소스는 엔티티(서버의 데이터 구조)라는 오해
• RESTful API에는 동사(Verb)를 쓰면 안된다는 주장
• 이런 것들은 설계 결정일 뿐 REST의 본질과는 직접 관련 없음

하이퍼미디어 구동(HATEOAS)의 실제 의미

• HATEOAS의 목적은 클라이언트-서버 결합도 최소화에 있음
• 서버의 URI 구조 변경 시, 클라이언트 재배포의 고통을 줄여 확장성과 진화 가능성을 높임
• 클라이언트는 문서나 사전 지식 없이 응답 내 하이퍼링크를 따라 동작을 탐색함 { "orderId": 123, "\_links": { "self": { "href": "/orders/123" }, "cancel": { "href": "/orders/123/cancel", "method": "POST" } } }
• 위와 같이 응답에 동작(링크)가 포함되어야 진정한 RESTful에 가까워짐

REST에서 리소스란?

• 리소스는 URI로 식별 가능한 모든 것
  • 문서, 이미지, 물리적 객체, 서비스, 추상 개념 등 포함
• 서버에는 실제 "리소스"가 존재하는 것이 아니라, URI로 접근 가능한 추상적 매핑 구조가 있을 뿐임
• RFC 3986에서도 리소스의 범위를 한정하지 않음
  • 전자 문서, 이미지, 정보원, 서비스, 심지어 사람·법인·도서 등도 포함 가능

Fielding이 정의한 RESTful API의 6가지 규칙

• 1. 단일 프로토콜에 종속되지 말 것
  • URI 기반 식별을 모든 프로토콜에서 활용 가능해야 함
• 2. 프로토콜(예: HTTP) 표준을 임의로 변경하지 말 것
  • 표준의 미비점 보완은 가능하나, 임의의 규칙 추가/변경 금지
• 3. URI 구조 대신 미디어 타입(포맷) 정의에 집중할 것
  • 데이터 형식 및 링크 정의에 집중, 경로 명세/문서화에 에너지 낭비 금지
• 4. 고정된 URI 네이밍/계층구조 하드코딩 금지
  • 클라이언트가 서버의 네임스페이스 구조를 추측·고정하지 않도록, 링크 기반 탐색 유도
• 5. 리소스 타입(내부 분류) 노출 금지
  • 내부 객체 타입은 클라이언트에 무의미, 표준 미디어 타입·링크만 노출
• 6. 북마크(초기 URI)만 필요, 나머지는 응답의 링크로 탐색
  • 클라이언트는 표준 미디어 타입만 알고, 상태 전이는 항상 서버 응답 내 하이퍼링크 기반으로 이뤄져야 함

규칙의 해석과 실제 적용

• 프로토콜, URI, 타입에 대한 결합을 최소화해야 진정한 RESTful에 가까워짐
• API는 데이터와 링크의 형식(미디어 타입)에 집중해야 하며, URI 구조나 명명 규칙 등은 클라이언트가 미리 알 필요 없음
• 예시처럼 /users/123/activate 같은 경로를 명세하지 않고, 응답 내 "activate" 링크로 동작을 안내해야 함

실제 RESTful API가 드문 이유

• OpenAPI, Swagger 등 도구의 편의성이 개발 현장에서 우선시됨
  • 자동 문서화, 코드 생성, 유효성 검사 등 실질적 이점 제공
• 클라이언트-서버를 같은 팀이 개발하는 SPA 환경에서는 URI 결합 문제의 필요성이 크지 않아, HATEOAS의 장점이 부각되지 않음
• REST 원칙의 초기 학습 부담, 동적 링크 파싱의 복잡성 등 실용적 장벽이 큼

결론

• Fielding의 규칙에 따르면 진정한 RESTful API는 하이퍼미디어(HATEOAS) 기반 동적 탐색이 필수임
• REST는 단순히 HTTP 위에서 CRUD를 구현하는 것이 아니며, 웹의 원리와 같이 느슨한 결합·진화 가능성·동적 상태 전이에 초점을 둔 아키텍처임
• 현실에서는 실용성과 팀의 상황에 맞는 설계가 더 중요할 수 있음
  • 외부 개발자를 위한 퍼블릭 API라면 HATEOAS 채택이 권장되지만, 내부 전용 API라면 단순한 RPC 스타일도 실용적임
• API는 배우기 쉽고 오용하기 어렵게 설계하는 것이 핵심이며, 반드시 RESTful일 필요는 없음