🚦 본론

REST란 무엇인가.

저는 일단 REST API라고 했을 때, 다음과 같은 의문점이 생겼어요.

REST API라고 하는데, 과연 이 REST란 무엇일까요?

따라서 이를 검색해본 결과, Representational State Transfer라고 합니다.
음... 해석하면 표현적인 상태 전달이겠죠?

이는 사실 HTTP 스펙을 정의하는 데 참여한 로이 필딩이 2000년, 네트워크 통신 관련 논문에서 주장하는 아키텍처 원칙이었어요.
그런데 그 내용이 많은 개발자들에게 받아들여졌고, 특히 네트워크는 거의 WWW가 차지했기에, 지금처럼 REST API라는 이름으로 유명해진 것이랍니다.

💡 중간 정리.

• REST는 광의적으로 네트워크에 관한 아키텍처 원리이며, 특히 Web에서 API를 설계하는 데 영향을 주었다.

조건

그렇다면 어떤 것을 RESTful하다고 표현할 수 있을까요?
본래 REST 아키텍처에는 제한 조건이 6가지가 존재합니다.

• Stateless 클라이언트의 콘텍스트는 정적인 상태를 유지해야 해요. 이는 HTTP 스펙과 일치하군요.
• Cache: 클라이언트는 응답을 캐싱할 수 있어야 해요.
• Client-Server: 클라이언트-서버로 각 기능이 독립적으로 유지되어야 해요.
• Layered System: REST 조건을 만족한다면, 요청 정보를 검색할 때 계층 구조로 분리되어야 해요.
• Uniform Interface: 구성 요소간에 URL, 응답 코드, 요청-응답 메서드에 있어서 통합 인터페이스를 사용해야 해요.
• Self-descriptiveness: 문서가 없더라도 쉽게 이해할 수 있어야 해요.

자. 이제 우리 주변 API를 둘러볼까요?

😖 ...뭐야, 내가 본 API, 정말 REST API 맞아...?

사실 생각보다, 이 REST API라는 게 여간 깐깐한 게 아니에요.
특히 저 굵게 표시한 저 두 개가 정말 골치 아프답니다.

Uniform Interface? 무슨 소리지?

핵심은 다음과 같습니다.

• 리소스 식별에 있어 URI 표준을 사용해요.
• 적절한 HTTP 표준을 사용해야 해요.
• MIME 유형과 RDF를 사용해서 API 스스로가 자기가 무엇인지 명시하는 메시지를 담고 있어야 해요.
• HATEOAS(Hypermedia As The Engine of Application State)라고 불리우는데, 하이퍼링크에 관계를 주석으로 담아, 클라이언트가 이해하는 데 어려움이 없어야 해요. 그렇기 때문에 클라이언트와의 분리가 가능해져요.

어떻게 보면 Self-descriptiveness가 여기에 녹여져 있어서 이 친구만 잘 유념해도 좋을 것 같아요.

하지만 프론트엔드로써 중요한 지점이 있어요.

API 자체가 어떤 내용인지 스스로가 알려줘야 진짜 RESTful한 친구이며,
HyperMedia(HyperLink)를 통해 마치 주석처럼 정보를 알 수 있어야 해요.

따라서 HATEOAS까지 지킨 REST API는 자신에 대한 API 주소를 가지게 되구요.
또한, API의 문서가 설명된 주소 및 기타 관련 API에 관한 링크를 모두 전달하게 됩니다.
실제로 써본다면, 마치 API를 통해 또다른 API로 연결할 수 있는 과정이 정말 재밌어요!

그리고 HATEOAS를 쓰기 위해서는, application/hal+json이라는 특이한 MIME 타입을 주어야 해요. 그래야 링크를 추가할 수 있다고 해요. 이 세부 과정을 여기에 담는 것은 논점을 벗어나는 것같아 이만 REST API에 대한 기본 설명을 끝내려 해요.

어때요. 단점이 딱 느껴지지 않나요?
만약 우리가 백엔드를 설계하고 제공한다면, 꽤나 귀찮고 복잡한 과정들을 거친다는 게 단점이겠죠?
그게 진짜 REST API가 잘 쓰이지 않는 이유입니다.

REST API의 구성

이런 내용들까지 넘어가는 건 정~말 머리 터질 것 같으니, 저자는 아마 간단하게 설명했던 것 같아요.
REST API는 자원, 행위, 표현이라는 3가지 요소로 구성되며, 이는 URI, 요청 메서드, 페이로드를 의미한다고 설명되어 있습니다.

맞습니다. 결국 이 친구들이 Uniform Interface에서 밑줄치지 않은 2개

• 리소스 식별에 있어 URI 표준을 사용해요.
• 적절한 HTTP 표준을 사용해야 해요.

와 일치하는군요!
사실, GET POST DELETE PUT PATCH 역시 어렵지 않아요.

1. 우리가 요청할 때
2. 어떤 목적을 갖고, 어떻게 전달할 것인지에 따라
3. 적절한 메서드를 쓰고 페이로드를 넣어주도록 백엔드와 설계하면 된답니다.

뭔가 갑자기 끝나는 것 같은데, 정리 한 번 하고 마무리하려 합니다.

정리.
우리가 알고 있는 REST API는 실제로는 반쪽짜리이다.
진짜 REST API는 훨씬 엄격하며, 따라서 API를 설계한다는 것은 API에 들어갈 리소스의 트레이드 오프를 잘 게산해서 설계해야 한다.
결국 우리 수준에서 일단 익히면 좋은 정도는 URI를 토대로 적절한 메서드를 쓰고 표준 HTTP 요청을 하는 정도라는 것이다.

🎉 마치며

사실 꽤나 낯설 수 있어요.
저도 예전에 halJSON을 처음 써봤을 때 매우 당황스러웠어요.

어...? 이렇게 작성한 API는 처음인데...?라는 느낌이었어요.

그런데 막상 써보면 굉장히 좋기는 합니다. (과할 정도로요.)
API를 모르면 링크를 통해서 RESTDocs의 내용을 볼 수 있고, 따라서 백엔드에게 추가로 질문할 것들이 많이 줄어들어요.

그렇지만, 굳이 링크를 엄격하게 다 전달할 필요는 없겠죠?
사실 API를 실무에서 쓰다 보면, DM으로 직접 물어봐도 되기도 하고, 연락하는 게 어렵지 않기 때문이죠.

따라서 이런 REST API를 온전히 다 지키기보다는, 적절한 컨벤션에 따라 API를 설계하는 게 저도 더 좋다고 생각하는 편입니다.

그럼, 즐거운 공부하시길 바라며. 이상!

📁 참고자료

HATEOAS를 이해하는 데 많이 도움이 됐던 블로그
Uniform interface - stackoverflow