RESTful API의 진실: HATEOAS와 현실 사이의 간극

RESTful API의 진실: HATEOAS와 현실 사이의 간극

Roy Fielding의 REST 원조 논문은 하이퍼미디어 기반 시스템 설계를 강조하지만, 현실에서는 많은 API가 중요한 REST 제약조건, 특히 HATEOAS를 구현하지 않고 RPC 스타일에 가깝게 설계되는 경향이 있습니다. 본 분석은 REST의 본질과 현대 개발 실무의 간극을 파헤치고 실질적인 설계 관점을 제시합니다.

핵심 기술

RESTful API 설계의 핵심 원칙을 재조명하고, HATEOAS의 중요성과 함께 실제 개발 환경에서의 실용성, 학습 부담, 그리고 대안적인 설계 접근 방식에 대해 논의합니다.

기술적 세부사항

• REST의 본질: Fielding의 논문은 HTTP 메서드나 CRUD 중심 설계를 필수로 규정하지 않으며, 하이퍼미디어(HATEOAS) 기반 상태 전이와 보편적 인터페이스를 강조합니다.
• HATEOAS의 중요성: 클라이언트-서버 결합도를 최소화하여 서버 URI 구조 변경 시 클라이언트 재배포의 고통을 줄이고 확장성과 진화 가능성을 높입니다. 응답에 동적 행동(링크)을 포함시켜 클라이언트가 동적으로 탐색하도록 합니다.
• 리소스의 정의: URI로 식별 가능한 모든 개념(데이터 구조, 엔티티, 문서, 이미지, 서비스, 추상 개념 등)을 포함합니다.
• Fielding의 6가지 규칙: 프로토콜 독립성, 프로토콜 표준 비변경, 미디어 타입 중시, 고정 URI 구조 금지, 리소스 타입 노출 금지, 링크 기반 탐색 등이 핵심입니다.
• 현실과의 괴리: OpenAPI/Swagger 등 문서화 도구의 편의성, SPA 환경에서의 HATEOAS 필요성 감소, 초기 학습 부담 및 파싱 복잡성 등이 실무에서 REST 원칙 준수를 어렵게 만듭니다.
• 개발 커뮤니티 반응: 많은 개발자가 REST의 본질보다 통용되는 의미(JSON 반환, CRUD 매핑)를 따르거나, HATEOAS의 실용성 부족을 지적하며 '결국 RPC'라는 의견을 제시합니다. 일부는 UX 최적화를 위해 REST의 이상과 충돌하는 선택을 하기도 합니다.
• 대안적 관점: 내부 전용 API의 경우 단순 RPC 스타일이 실용적일 수 있으며, API는 배우기 쉽고 오용하기 어렵게 설계하는 것이 중요합니다. 모든 상황에서 엄격한 RESTful 준수보다는 실용성과 팀 상황에 맞는 설계가 우선될 수 있습니다.
• HTML과의 유사성: HTML 문서의 링크 기반 탐색은 HATEOAS의 좋은 예시로, UI를 위한 방식과 API를 위한 방식을 구분하는 것이 중요합니다.
• AI와 API 소비: AI 시대에 API의 discoverability는 중요해질 수 있으며, HATEOAS는 이러한 잠재적 이점을 가질 수 있습니다.
• 실용적인 라이브러리: htmx와 같은 라이브러리는 HATEOAS를 더 실용적으로 구현하려는 시도로 볼 수 있습니다.

개발 임팩트

REST의 원칙, 특히 HATEOAS를 제대로 이해하고 적용하면 시스템의 유연성, 확장성, 진화 가능성을 크게 높일 수 있습니다. 하지만 실무에서는 기술 부채 관리, 개발 속도, 팀 역량 등을 고려하여 하이브리드 접근 방식을 채택하거나 현실적인 타협점을 찾는 것이 중요합니다. HATEOAS를 엄격히 준수하는 시스템은 서드파티 API나 공개 데이터 포털 등에서 큰 가치를 발휘할 수 있지만, 모든 웹 애플리케이션에 동일하게 적용되는 것은 아닙니다.