[HTTP] 완벽한 RESTful 설계가 가능할까?

하원·2024년 7월 22일

안녕하세요, 하원입니다.
오늘은 RESTful 설계에 대해 소개해 보겠습니다.

REST & RESTful

종종 백엔드 개발자들이 RESTful하게 API를 설계한다고 말합니다.
RESTful하게 API를 설계할 때, 자원을 표현하는 URI는 명사로, 행위에는 동사가 들어가면 안 된다고 합니다.

하지만 이러한 규칙을 지키다 보면 괴상한 URI들이 등장하곤 하는데요,
과연 REST와 RESTful은 대체 무엇을 의미하고, 왜 등장했으며, 어떤 특징이 있을까요?
그리고 완벽한 RESTful API 설계가 무조건적으로 좋은 것일까요?

REST

정의

REST는 Representational State Transfer의 약자로, 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처의 한 형식이라고 합니다.
네트워크를 통해 컴퓨터끼리 통신할 수 있게 해주는 아키텍처 스타일입니다.
HTTP URI를 통해 자원(Resource)을 명시하고, HTTP Method(GET, POST, UPDATE, DELETE, PUT 등)를 통해 해당 자원에 CRUD Operation을 적용하는 것을 의미합니다.

등장배경

기존에 존재했던 SOAP API 방식은 보안 관련 표준들이 많아 금융 정보와 같은 보안에 민감한 데이터를 주고받을 때 많이 사용되었다고 합니다.
즉, 이러한 표준들로 인해 오버헤드가 많이 발생하여 웹 서비스에는 적합하지 않았다는 겁니다.
이러한 SOAP API 방식의 불편한 점을 기존의 HTTP 방식(HTTP Protocol, HTTP Method, HTTP Status Code)과 JSON을 사용하여 SOAP보다 상대적으로 더 가볍게 만든 것이 REST 방식이라고 합니다.
SOAP API 방식은 XML 데이터 포맷만 사용 가능합니다.

구성요소

자원(Resource) - HTTP URI
- 보통 API Sheet를 보면 /members, /posters 등을 확인할 수 있는데 해당 명사들을 자원이라고 말합니다.
행위(Verb) - HTTP Method
- 자원에 대한 행위를 HTTP Method(GET, POST, UPDATE, DELETE, PUT 등)를 통해 지정할 수 있습니다.
표현(Representation of Resource) - JSON, XML, TEXT, RSS 등
- 클라이언트가 자원의 상태에 대한 조작을 요청하면 서버가 이에 대한 응답을 보냅니다.
- 이때 JSON, XML, TEXT, RSS 등 여러 표현 형태를 사용하는데, 현재는 보통 JSON을 사용합니다.

특징

1. 서버-클라이언트 구조

자원이 존재하는 Server, 자원을 요청하는 Client로 나뉩니다.

2. 무상태성(Stateless)

HTTP 프로토콜을 사용하기 때문에 무상태성(Stateless) 특징을 갖습니다.
Client의 context를 Server에 저장하지 않습니다.

3. 캐시 처리 가능

HTTP 프로토콜을 사용하기 때문에 캐시 처리가 가능합니다.

4. 계층화

Server는 보안, 인증, 로드밸런싱 등 다중 계층으로 구성할 수 있습니다.

5. 인터페이스 일관성

자원을 URI로 지정하여 조작하기 때문에, HTTP 프로토콜을 따르는 모든 플랫폼에서 사용 가능합니다.
즉, HTTP 프로토콜을 따른다면 특정 언어나 다른 기술들에 종속되지 않습니다.

REST API와 RESTful API의 차이점

REST API

: REST 아키텍처를 기반으로 하는 API를 의미합니다.

RESTful API

: REST API를 제공하는 웹 서비스를 의미합니다.

RESTful

: REST API 설계 규칙을 지킨 시스템을 RESTful하다고 말합니다.

REST API와 RESTful API는 사실상 비슷한 맥락의 단어지만, REST 원칙을 잘 따른다는 것을 강조할 때 RESTful이라는 단어를 사용한다고 합니다.

RESTful API 설계

그러면 RESTful하게 API를 설계할 때 어떤 규칙을 따를까요?

1. 자원을 표현할 때

동사보다는 명사로 표현
대문자보다는 소문자로 표현
자원이 Document(단일 개념)일 때는 단수 명사 사용
자원이 Collection(서버가 리소스 관리)이나 Store(클라이언트가 리소스 관리)일 때는 복수 명사 사용

2. 자원에 대한 행위를 표현할 때

동사 표현이 들어가지 않도록 주의, ex) /members/join
HTTP Method가 들어가지 않도록 주의, ex) /members/delete/1

3. 슬래시( / )로 계층 관계를 나타내기

또한, URI의 마지막에는 슬래시( / )를 사용하지 않기

4. 언더바( _ ) 대신 하이픈( - )을 사용

긴 URI가 필요한 경우, 하이픈을 사용

5. 파일 확장자를 URI에 포함하지 않기

ex) /posters/1/image.png

RESTful 규칙을 항상 지켜야 하나요?

위와 같이 다양한 RESTful 규칙들이 존재합니다.
규칙들을 하나씩 살펴보면 어려운 규칙도 없고 꽤 간단하다고 볼 수도 있습니다.

하지만 위 규칙들 중 자원에 대한 행위를 표현할 때 동사 표현이 들어가지 않도록 설계해야 한다는 규칙이 개인적으로 까다로웠는데요..!

가끔 HTTP Method로 구분하기가 힘들고, 행위를 명사로 표현하기 힘든 경우가 존재합니다.
만약 어떤 API의 결과가 자원을 생성하거나 조작시키는 것이 아닌 프로세스를 처리해야 하는 경우라면, 어쩔 수 없이 동사를 사용할 수밖에 없습니다.

컨트롤 URI

이럴 때 사용하는 URI를 컨트롤 URI라고 부릅니다.
HTTP Method로 해결하기 어렵거나 애매한 경우에 사용하며, 실무에서도 많이 사용한다고 합니다.

또한, 최근 DELETE와 PUT과 같은 HTTP Method의 보안 취약 문제로 인해 사용하지 못하도록 차단하는 서버들이 존재합니다.
그래서 최근에는 동사형 단어를 사용하여 자원을 관리하는 설계 방법도 종종 사용한다고 합니다.

Ex)
결제 승인 : /payments
결제 취소 : /payments/cancel

완벽한 RESTful?

위와 같이 컨트롤 URI를 사용하게 되면 동사형 단어 사용으로 인해 RESTful 규칙에 어긋나겠죠?

하지만 REST나 RESTful 자체가 URI만 보고 어떤 기능을 수행하는지 한눈에 알 수 있도록 간결하게 표현하는 것이 목적이었기 때문에, 과도한 명사형 단어 지향으로 의미가 직관적으로 해석되지 않는 순간 그것은 REST의 의도에서 벗어난다고 생각합니다.

따라서 적절한 동사형 컨트롤 URI를 사용해 주는 것이 개인적으로 REST의 의도에 적합하다고 생각하는 바입니다.

마무리

RESTful 설계는 팀 프로젝트를 진행하면서 접해보게 되었다.
많이 들어보긴 했지만, 자세히 알지는 못해서 팀원들이 추천해 주는 URI를 그대로 사용한 적도 있었다.
하지만 과도한 명사형 단어를 사용하다 보니 URI가 괴상해지면서 이게 RESTful의 의도가 맞는 건지 의심이 되었다.
그래서 해당 포스팅을 작성하게 되었고, 이제는 REST의 탄생 배경과 여러 가지 의도를 알게 되면서 앞으로는 유연한 RESTful 설계를 해야겠다고 생각하게 되었다.

참고

하원

호기심 저장소

이전 포스트

[Spring] 엔티티를 Response에 넣으면?

다음 포스트