난 REST API를 쓰고있는가? (Feat. HTTP API)

REST API ? HTTP API?

여느 때처럼 AWS 제품군을 구경 중에 AWS API Gateway를 발견해 구경하고 있었다.

 

평소에 리버스 프록시 쪽에도 관심이 많았기 때문에

 

열심히 구경하고 있는데....

 

 

REST API와 HTTP API ?

 

이게 이렇게 엄격히 구분되는 개념이었나? 라는 생각이 먼저 들었다.

 

REST API가 뭔진 알고 있는데, HTTP API는 뭐고 구분짓는 기준이 뭔지가 궁금했다.

 

우선 REST API에 대해 정리해보자.

 

좀 오래된 내용이지만 아래 유튜브를 참고했다.

 

https://www.youtube.com/watch?v=RP_f5dMoHFc&t=1s&ab_channel=naverd2

REST API의 제약 조건

일단, HTTP API가 조금 더 넓은 범주를 이야기한다는건 부정할 수 없는 사실이다.

 

REST API는 좀 더 엄격한 기준을 요구한다.

 

REST API의 제안자인 Roy Fielding 박사는 당신들이 이야기하는 것들은 REST API가 아니야!! 라고 한다. 그만큼 엄격한 기준이 있다는 뜻이다.

 

조금 오래된 글이지만 2008년에 Roy Fielding 선생님이 쓰신 article 중 일부이다. 

 

https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

There are probably other rules that I am forgetting, but the above are the rules related to the hypertext constraint that are most often violated within so-called REST APIs. Please try to adhere to them or choose some other buzzword for your API.

 

REST API에서 가장 안지켜지는 하이퍼텍스트 제약 조건(hypertext constraint)에 대해 이야기하며 글을 마무리 하면서 이를 준수하지 못한다면, 그 API에 대한 다른 유행어를 선택하라고 했다.

 

그렇다면 REST API의 제약 조건에 대해 알아보자.

 

위 조건들이 Roy Fielding 박사의 논문에서 언급한 제약 조건들이다.

 

1. 클라이언트-서버(client-server) : 클라이언트-서버 제약 조건은 사용자 인터페이스와 데이터 스토리지의 문제를 분리하여 독립적으로 발전할 수 있도록 한다.
2. 상태 비저장(stateless): REST API는 stateless이다. 즉, 각 요청에는 요청을 완료하는 데 필요한 모든 정보가 포함된다.
3. 캐시 가능(cache): REST API의 응답은 향후 요청에 재사용할 수 있는지 여부에 따라 캐시 가능 또는 캐시 불가로 표시되어야 한다.
4. 균일한 인터페이스(uniform interface): 균일한 인터페이스 제약 조건은 클라이언트가 리소스와 상호 작용하는 방식에 대한 제약 조건 집합을 정의한다. 리소스를 설명하기 위한 표현(예: JSON 또는 XML) 사용이 포함됩니다.
5. 계층화된 시스템(layered system): 프리젠테이션 계층, 애플리케이션 계층 및 데이터 스토리지 계층과 같은 애플리케이션의 여러 계층 간에 관심사를 분리해 확장성과 모듈성이 향상시켰다.
6. Code-On-Demand(선택 사항): Code-On-Demand 제약 조건은 선택 사항이며 클라이언트 측에서 실행될 JavaScript 또는 애플릿과 같은 실행 가능한 코드의 전송을 허용합니다.

 

여기서 거의 모든 제약 조건을 잘 지키는데, 이중에 Uniform Interface를 잘 지키지 못한다고 한다.

 

특히 JSON 규격의 API에서...

 

그래서 뭘 못 지키고 있나?

 

• Indetification of resources : 리소스가 URI로 식별된다.
• manipulation of resources through representations : 리프리젠테이션 전송을 통해서 리소스를 조작해야 한다. 리소스를 만들거나, 수정하거나, 삭제할 때 Http 메시지에 표현을 담아서 전송해야 한다.

 

위 두 가지는 잘 지켜지고 있다. 그러나 아래 두 가지는 REST API 라고 알려진 거의 모든 것들이 지키지 못하는 것들이다.

• Self-descriptive message : 메시지는 스스로를 설명해야 한다
• hypermedia as the engine of application state(HATEOAS): 애플리케이션의 상태는 Hyperlink를 이용해 전이되어야 한다.

 

뭐가 문제인걸까?

 

Self-descriptive message

• Request에서의 Self-descriptive message를 만족하는 경우. 목적지를 꼭 써줄 것

 

 

• json으로 표현했을 때 Response에서는 Self-descriptive message를 만족하기 어렵다.
• op와 path가 뭔지 모르기 때문이다. 매번 정확히 표현하기 어렵기 때문에, json에서는 위 조건을 만족하기 어렵다.

 

hypermedia as the engine of application state(HATEOAS)

• 하이퍼 링크(a 태그)로 상태 전이를 하기 때문에 HATEOAS 제약 조건을 만족 한다.

 

 

• json으로 표현했을 때, HATEOAS 제약 조건을 만족하는 경우이다.
• 일반적으로 알고있는 JSON 규격과는 거리가 있어보인다...

 

 

왜 지켜야하나?

 

위와 같은 이유다.

 

하위호환성과, 상호운용성을 유지 해내기 위해 지켜야한다.

 

이름에 괜히 프로토콜이 들어가 있는게 아니다.

 

그래서 HTTP API와의 차이점은?

• 웹 페이지들은 사람이 보지만, API는 기계가 해석함
• 웹 페이지는 HTML이고 HTTP API인 경우에는 JSON이나 XML같이 기계가 이해할 수 있는 기계가 의미를 이해할 수 있는 포맷을 쓰게 된다.
• 때문에, Self-descriptive를 만족하기 어렵고, 어떤 의미인지 파악하기 위해서는 별도로 API 규격서와 같은 문서가 필요하게 된다.

 

일단 Media Type이 JSON이 되면, 별도의 문서가 없을 경우 명확히 메시지의 내용을 설명할수 없게 되므로 REST API라고 하기 어려워진다.

 

그렇다면 일반적으로 위 모든 사항이 고려되지 않은 API들은 전부 HTTP API로 분류된다.

 

따라서, HTTP API가 좀 더 넓은 범위의 HTTP 프로토콜이라 할 수 있다.

 

HTTP API는 제약조건에 조금 더 자유로우며, 다양한 방식으로 구현될 수 있으며 구조화 방법을 결정하는 것은 순수히 백엔드 개발자의 몫이다.

 

마치며

내가 작성한 내용에는 REST API의 모든 제약 조건이 포함되지 않았다.

(사실 더 다양한 예시가 있다)

 

위 제약조건들을 100% 따르기 어렵기 때문에(제안자가 요구하는 정도의) 사실상 우리가 우리는 REST API를 쓰고 있어!! 라고 말해도, Roy Fielding 박사는 그것은 REST API가 아니다 라고 단언 할 것이다.

 

하지만 너무 오랫동안 REST API라고 생각하고 구현한 HTTP API를 REST API라고 불렀기 때문에, 그냥 그대로 부르면 된다.

---

• 참고사이트
  https://www.tinystacks.com/blog-post/api-gateway-rest-vs-http-api-what-are-the-differences/
  https://www.youtube.com/watch?v=RP_f5dMoHFc&t=1s&ab_channel=naverd2