백엔드 개발을 하다보면 'RESTful API로 만들자', '이건 REST스럽지 않다.' 라는 말을 듣거나 쓰게된다.
RESTful과 RESTless의 기준이 대체 뭘까.
이 글에서는 REST API의 본질부터 RESTful vs RESTless를 정리해보고자 한다.
REST?
REST(Representational State Transfer) 아키텍처 스타일의 설계 원칙을 준수하는 API
-> 자원을 이름으로 구분하여 해당 자원의 상태를 주고받는 모든 것을 의미
-> HTTP 프로토콜 위에서 동작하며, 자원을 URI로 표현하고, 상태를 HTTP 메서드로 처리
REST API 설계 원칙
- 균일한 인터페이스
- 동일한 리소스는 어디서 접근하든 일관된 방식으로 표현돼야 함
- 하나의 URI에 하나의 리소스만 연결되어야 함
- 클라이언트 - 서버 분리
- 클라이언트는 서버의 내부 구조를 몰라도 되고
- 서버도 클라이언트의 상태를 알 필요 없음 → 책임 분리
- 무상태성
- 각 요청은 독립적이며, 필요한 정보는 요청 안에 모두 포함되어야 함
- 서버는 이전 요청의 상태를 저장하지 않음
- 캐시 가능성
- 리소스는 클라이언트/서버에서 캐싱 가능해야 하며,
- 응답에 캐시 가능 여부를 명시해야 함
- 계층화된 시스템
- 클라이언트는 응답을 주는 대상이 서버인지, 프록시인지 몰라도 됨
- 중간 계층(캐시 서버, 로드 밸런서 등) 사용 가능
- 코드 온디맨드(선택사항)
- 필요 시 서버는 실행 가능한 코드를 클라이언트로 전달 가능
- 유연성은 높이지만 잘 쓰이지는 않음
REST API의 개념과 원칙에 대해 간단히 살펴봤으니 이제 본론으로 넘어가보자!
RESTful vs RESTless API
RESTful API는 정확히 어떤 기준을 만족해야 하고,
RESTless API는 왜 REST와 다르다고 하는 걸까?
✅ RESTful API란?
RESTful API는 앞서 설명한 REST 아키텍처의 제약조건(6가지 원칙)을 따르는 방식으로 설계된 API를 말한다.RESTful한 설계는 다음과 같은 기준을 지닌다.
| 요소 | 설명 |
|---|---|
| 자원 중심 설계 | URI는 동작이 아닌 자원(명사)을 표현해야 한다 |
| HTTP 메서드 활용 | GET, POST, PUT, DELETE 등의 의미를 역할에 맞게 사용 |
| 무상태성 | 각 요청은 독립적이며, 서버는 클라이언트 상태를 저장하지 않음 |
| 일관성 | URI 패턴, 응답 형식, 상태 코드의 사용이 일관되어야 함 |
예를 들어 🔻
GET /users/1 → 사용자 정보 조회
POST /users → 사용자 생성
PUT /users/1 → 사용자 정보 전체 수정
PATCH /users/1 → 사용자 정보 일부 수정
DELETE /users/1 → 사용자 삭제URI에는 리소스만 명시하고, 동작은 HTTP 메서드로 구분하는 것이 핵심이라고 보면 되겠다.
✅ RESTless API란?
RESTful API는 REST 아키텍처의 원칙을 충실히 따르는 반면, RESTless API는 이러한 원칙을 완전히 따르지 않거나 다른 프로토콜을 사용하는 API다. 이러한 차이는 API의 설계, 구현, 유지보수에 영향을 미친다.
RESTless API의 특징은 뭘까.
- 동작 중심 URI: URI에 동사가 포함되어 동작을 표현하는 경우
- HTTP 메서드 남용: GET으로 데이터를 수정하거나 POST만 사용하는 등 메서드의 역할이 불분명한 경우
- 자원과 행위 혼재: URI에 동작과 자원이 섞여 있는 경우
- 무상태성이 깨질 수 있음: 서버가 클라이언트의 상태를 저장하는 경우
예를 들어 🔻
GET /getUserById?id=1
POST /createNewUser
GET /updateUserStatus?id=1&active=true
감이 오지 않는다... 더 찾아보자
RESTless 웹 서비스 또는 API는 REST 원칙을 따르지 않는다.
대신 SOAP(Simple Object Access Protocol) 과 같은 다른 프로토콜을 따른다.
📌 SOAP란?
SOAP는 XML 기반의 메시지 교환 프로토콜로,
웹 서비스에서 요청과 응답을 엄격한 형식의 메시지(XML)로 주고받는다.
SOAP는 다음과 같은 특징을 가진다:
- 계약 기반 통신 : API 명세가 미리 정의된 문서를 통해 주고받음
- 엄격한 구조: 요청/응답 모두 XML로 정의되며, 구조가 엄격하다
- 확장성: 보안, 트랜잭션 등 다양한 기능을 내장하고 있음
- HTTP 이외의 프로토콜도 사용 가능 (예: SMTP)
🧐 왜 RESTless는 RESTful보다 덜 선호될까?
"RESTless API는 때때로 필요할 수 있지만, 많은 개발자들이 RESTful API를 더 선호하는 데는 이유가 있다."
- 표현이 직관적이지 않다.
/getUserById 같은 동사 중심 URI는 명확하지 않고 일관성이 떨어진다.
GET /getUserById?id=1 POST /createNewUser GET /updateUserStatus?id=1&active=true🔎 URI마다 이름이 다 다르다면 → 새로운 API를 볼 때마다 "이건 뭐 하는 거지?" 고민해야 한다.
- HTTP 메서드 의미가 불분명하다.
HTTP 메서드(GET, POST, PUT, DELETE 등)는 본래의 의미가 있고 기능별로 분리되어야 한다.
그런데 RESTless에서는 그냥 POST로 다 처리해버리는 경우가 많아서, 클라이언트 입장에서 무슨 동작을 하는 API인지 유추가 어려워진다.POST /doEverything🔎 이렇게 모든 동작을 POST로만 처리하면, 데이터를 조회하려는 건지, 수정하려는 건지 알 수 없다.
- 무엇보다 어렵다.
SOAP는 구조가 엄격하고, 익숙해지기까지 시간이 걸린다.
XML, 스키마, 도구 등 익혀야 할 개념이 많아 진입장벽이 있다.
❓ 그럼에도 불구하고 RESTless API를 선택할때는 어떤때일까?
- 금융, 보험, 정부 기관 등에서는 보안, 트랜잭션, 신뢰성이 중요한데 SOAP는 이러한 요소를 내장하고 있기 때문에 여전히 사용되기도 한다.
- 내부 시스템 통신에서 기존 SOAP 기반 시스템과 연동이 필요한 경우에도 사용한다.
이처럼 RESTless는 단순히 REST 원칙을 어긴 설계뿐만 아니라,
SOAP 기반처럼 완전히 다른 접근 방식을 사용하는 API까지 포함하는 더 넓은 개념이다.
깨달음
RESTful이 기준이라면, RESTless는 선택이다
RESTful API는 명확한 표현 방식과 설계 철학을 지닌다.
일관성 있는 URI, 명사 중심의 자원 설계, HTTP 메서드의 역할 분리 등은 유지보수성과 확장성을 높이는 데 큰 도움이 된다.
하지만 현실의 API 설계는 언제나 이상적인 상황과는 다르다.
비즈니스 로직이 복잡하거나, 빠르게 기능을 구현해야 하는 경우, 혹은 기존 시스템과의 통합이 필요한 경우에는 REST 원칙을 일부 어기고 RESTless 방식으로 설계하는 것이 더 실용적일 수 있다.
예를 들어:
POST /users/1/deactivate → 사용자 비활성화
POST /orders/1/cancel → 주문 취소 이러한 API는 완전히 RESTful하진 않지만, 의도를 명확하게 표현하고 프론트엔드 개발자에게 직관적으로 동작을 전달할 수 있다는 장점이 있다.
단순히 RESTful API를 사용해야 한다고만 생각했던 건 오산이었다.
REST 설계 원칙은 엄격한 규칙이 아닌 "지향점"이다. 중요한 것은
- 왜 이 API는 RESTful하게 만들지 않았지?
- 이 방식이 향후 유지보수와 팀 협업에 어떤 영향을 끼칠까?
- 이 선택이 사용자와 개발자 모두에게 명확할까?
이 질문들에 내가 답을 할 수 있는가이다.
즉 내가 설계한 API가 어떤 방식이든 간에, 그 설계가 이해 가능하고 유지 가능하며, 비즈니스에 적합한지를 고민해야 하는 것이다.
"REST는 목표, 실무는 언제나 유연해야 한다."
[참고자료]
https://dev.to/krishnaa192/restful-vs-restless-api-276
https://www.ibm.com/kr-ko/topics/rest-apis
https://talent500.com/blog/restful-vs-restless-api-in-backend/
https://tutorialedge.net/software-eng/what-is-a-rest-api/
