'그런 REST API로 괜찮은가' 학습노트

2019-07-10

Data Engineering

이응준님 ‘그런 REST API로 괜찮은가’ 발표내용 정리 (REST API 기초개념 학습)

URL : https://tv.naver.com/v/2292653

우리가 개발을 하거나 코드리뷰를 하는데 “왠지 그부분은 REST스럽지 않은거 같네요” 라는 이야기를 종종 들을 수 있다. 그러나 정확하게 REST가 어떤것인지 잘 감이 안온다.
REST의 정의를 보면 이런식으로 되어있다.

REpresentational State Transfer의 약자인데 우리는 이말을 보고 REST가 무엇인지 전혀 모르겠다. 또한 컴퓨터 시스템간의 상호운영성을 제공하는 방법이라고 하는데 무슨말인지 감이 안온다.

그래서 우리는 REST라는 개념이 왜 나왔는지 히스토리를 알 필요가 있다.

1991년 WEB이 팀버너스리로부터 탄생할때로 돌아가자. 이때 이미 인터넷은 나와 있었지만 어떻게 인터넷에서 정보를 공유할것인지 그것이 고민한 결과로 나온 것이 WEB이다.

정보들을 하이퍼텍스트로 연결하는것이 핵심이었다. 표현방식은 HTML, 식별자는 URL, 전송방법은 HTTP 라는 것을 만들었다.

그래서 HTTP라는 프로토콜을 여러사람들이 설계하게 되었다. 그 여러사람중에 한명이 로이필딩이라는 사람이었다. 로이필딩이라는 사람이 HTTP를 만드는 작업에 참여를 하면서 고민이 하나 있었다. 1994년 HTTP 1.0이 나오기 전에 WWW에서 이미 어느정도 이용되고 있었고, 웹은 급속도록 성장중이었고, 이미 전세계에 수많은 웹서버가 이미 존재하고 있었다. 이런시점에서 로이필딩은 HTTP를 정립하고 기존의 기능들을 보완해야 하는 상황에 놓여있었다. 그러면 로이필딩이 HTTP를 고치게되면 당연히 기존에 구축해놓은 웹과 호환성에 문제가 생길 수 밖에 없었다.

로이필딩은 고민했다. 어떻게하면 기존의 웹과 호환성을 가져가면서 HTTP를 발전시킬 수 있을까. 이런 고민결과 HTTP Object Model이라는 것을 만들었다. 사실 이것이 4년뒤에 REST라는 이름으로 발표된다.

로이필딩이 1998년에 마이크로소프트사에서 “Representational State Transfer”라는 이름으로 REST를 발표한다. 그리고 2년뒤 2000년에 2년전 REST를 발전시켜서 발표한 박사논문이 우리가 오늘날 알고있는 그 REST를 정의하는 논문이다.

그런 한편 인터넷상에는 API라는게 만들어지기 시작했다. 1998년에 마이크로소프트사에서 XML-RPC라고 원격으로 단일시스템의 메소드를 호출할 수 있는 프로토콜을 만들었다. 이게 나중에 SOAP이라는 이름으로 바뀌게 된다. SOAP(Simple Object Access Protocol)은 일반적으로 널리 알려진 HTTP, HTTPS, SMTP 등을 통해 XML 기반의 메시지를 컴퓨터 네트워크 상에서 교환하는 프로토콜이다. 그리고 salesforce라는 회사에서 2000년에 어떤 API를 공개하는데 세계최초의 오픈 API라고 할 수 있을것이다. 이때 당시 SOAP을 사용해서 API를 만들었는데 아래 그림과 같이 어떤 아이디로 object 하나를 가져오는 API의 요청메시지로 되어 있는데 상당히 복잡하다. 그래서인지는 모르겠는데 saleforce API는 장사가 잘 안되었다는 후문이 있다.

4년후에 flickr라는 곳에서 API를 출시했는데 얘네는 여러가지 형태로 만들었다. 위에처럼 SOAP형태로도 만들었는데 REST로도 공개를 했다. 그당시에 사람들에게는 신기술로 보였다. 사실 2000년에 논문으로 나온 내용을 그대로 응용해서 만든것이었다. 아래 그림과 같이 똑같은 내용이지만 SOAP에 비해 REST가 상당히 코드가 짧은것이 인상적이었다. 그래서 사람들은 비교를하기 시작했다. SOAP은 복잡하고, 규칙이 많으며, 어렵지만 반면에 REST는 단순하고, 규칙이 없으며, 쉽다.

이결과 SOAP은 사용빈도가 추락하게 되고 반면에 REST는 인기가 급상승했다. 그리고 2006년 AWS에서는 자사의 API 사용량의 85%가 REST임을 공개했다. 2010년에는 salesforce조차도 REST API를 지원하게 된다. 즉 REST가 SOAP을 이기게 된다. 그래서 WWW의 API가 모두 REST로 정착이 되나 싶었다.
그런데 2008년에 CMIS라는 것이 나왔다. 이것은 CMS에 대한 표준이고, IBM과 MS사 같은 큰 IT 기업들이 참여해서 만들었다. 그리고 이 CMIS가 REST 바인딩을 지원했다. 그런데 그걸 본 로이필딩이 이런말을 한다. “CMIS에 REST는 없다” . 다른사람이 볼때는 REST로 보였는데 REST를 만든 로이필딩은 이게 REST가 아니라고 말하게 된다.
그리고 2016년에는 마이크로소프트사가 REST API 가이드라인이라는 것을 만들었다. GET, PUT, DELETE 등의 메서드를 지원해야하고, URL은 일정한 형식을 지켜야 하는 등등이 포함되어 있는 내용이었다. 사람들이 보기에는 납득할만한 얘기였고 올바른 REST API에 관한 얘기였다. 그런데 로이필딩이 트위터에 이것도 REST API가 아니라고 저격한다. 로이필딩은 또한 이런말을 한다. REST API는 반드시(must) hypertext-driven이어야 한다. 또 REST API를 위한 최고의 버저닝 전략은 버저닝을 안하는 것이라고 한다.
사람들이 알고 있는 REST API와 정작 REST를 만든 로이필딩의 생각이 너무 다르다. 도대체 왜 이런 차이가 있는 것일까. REST API에 대해 하나씩 따져보자.

REST API : REST 아키텍처 스타일을 따르는 API

REST : 분산 하이퍼미디어 시스템(예를 들어 웹)을 위한 아키텍처 스타일 (로이필딩의 박사학위 논문의 정의를 그대로 인용)

아키텍처 스타일 : 제약조건들의 집합이다. 그래서 이런 제약조건들을 모두 지켜야 REST를 따른다고 말할 수 있다.

그러면 REST를 구성하는 제약조건이 어떤것이 있는가.(REST를 구성하는 스타일).

REST는 아키텍처 스타일이면서 동시에 하이브리드 아키텍처 스타일이라고 말한다. 왜냐하면 아키텍처 스타일인데 동시에 아키텍처 스타일의 집합이기 때문이다. 그래서 아래와 같이 6가지 아키텍처 스타일로 구성되어 있다.

1) 클라이언트 - 서버

2) stateless

3) cache

4) uniform interface

5) layered system

6) code-on-demend (optional)

대체로 오늘날 REST API라고 불리우는 것들은 이 6가지를 잘 지키는 편이다. 왜냐하면 이미 HTTP만 잘 따라도 6)빼고 다 잘 지키게 되어있기 때문이다. 코드온디멘드는 서버에서 코드를 클라이언트로 보내서 실행할 수 있어야 한다는 말이다. 여기서 우리는 자바스크립트를 바로 떠올릴수 있다. 그래서 대체로 이런 아키텍처 스타일을 잘 지키는데 이중에 ‘유니폼 인터페이스’라는 것은 잘 안지켜지는 편이다.

Uniform interface 스타일(의 제약조건)

1,2번은 대부분 다 잘 지켜지는 편인데 3,4번이 문제였다. 자칭 REST API라고 오늘날 알려져있는 거의 모든것들이 이 3,4번은 지키지 못하고 있다.

1) identification of resources = 리소스가 URL로 식별되면 된다.

2) manipulation of resources through representations = representation 전송을 통해서 리소스를 조작해야 한다. 어떤 리소스를 만들거나 업데이트하거나 삭제할때 HTTP 메세지에 표현을 담아서 전송해서 원하는 것을 달성할 수 있어야 한다는 것이다.

3) self-descriptive messages = 메세지는 스스로를 설명해야 한다.

예를들어 GET / HTTP/1.1 이라는 메세지가 있다고 하자. 그냥 루트를 얻어오는 단순한 get 메서드로 보내는 요청메세지인데 여기에는 목적지가 빠져있다. 다시말해서 이 HTTP 요청 메세지는 뭔가 빠져있어서 self-descriptive하지 못하고 하는 것이다.

GET / HTTP/1.1

host : www.example.org

위와 같이 목적지를 추가해주면 비로소 self-descriptive하다고 할 수 있다.

또 다른 예시를 들어보자. 응답메세지인데 200 OK로 응답을 하고 안에 제이슨으로 된 본문이 있다. 이거역시 self-descriptive하지 않다. 왜냐하면 클라이언트가 응답을 받고 이걸 해석해야 하는데 이게 어떤 문법으로 작성된건지 모르기 때문이다.

그래서 아래 그림과 같이 컨텐츠 타입 헤더가 반드시 들어가야 한다. 이 헤더가 들어있으면 본문의 내용을 정확하게 인식하여 파싱할 수 있고, 문법을 정확하게 해석할 수 있게된다. 여기까지 해준다고해서 self-descriptive 한것은 아니다. 본문이 어떤건지 인식했다고 해도 본문안에 op가 뭐지? path는 뭐지? 모르기 때문이다.

아래 그림과 같이 json-patch+json이라는 미디어 타입을 정의해줘야 json-patch에 대한 명세를 찾아가서 이거를 이해한 다음에 이 메세지를 해석하면 비로소 올바르게 이 메세지의 의미를 이해할 수 있다.

이처럼 self-descriptive message라고 하면 이 메세지를 봤을때 메세지의 내용으로 온전히 해석이 전부 가능해야 한다. 그러나 오늘날 거의 대부분 REST API가 이걸 만족하고 있지 않다. 대부분은 그냥 제이슨이라고만 명세하고 있지 이처럼 정확하게 표현하고 있지는 않다.

4) hypermedia as the engine of application state (HATEOAS) = 어플리케이션의 상태는 하이퍼링크를 이용해 전이되어야 한다.

예를 들어 아래 그림과 같은 웹사이트가 있다고 가정하자.

웹사이트의 루트에 접근하면 단순한 게시판이 나오는데 게시판 전체 목록을 볼 수 있는 링크가 있고, 링크를 누르면 글 목록보기를 위한 HTTP 요청을 보내서 글목록을 가져오고, 그리고 다시 글쓰기 링크가 있어서 글쓰기 링크를 누르면 글쓰기 form이 나오고 글쓰기 폼을 채워서 글쓰기 저장을 누르면 저장이 되고 내가 저장된 글을 볼 수 있는 대략적인 구조이다. 이런 구조가 애플리케이션의 상태가 전이된다고 할 수 있다. 위의 그림처럼 상태의 전이때마다 항상 해당페이지에 있던 링크를 따라 전이 했기 때문에 얘는 HATEOAS가 된다.

아래 그림과 같이 a 테그를 통해서 하이퍼링크가 나와있고, 하이퍼링크를 통해서 그 다음 상태로 전이가 가능하기 때문에 HATEOAS가 만족된다.

아래 그림과 같이 JSON 형식으로도 HATEOAS를 만족할 수 있다. 링크라는 헤더가 이 리소스와 하이퍼링크로 연결되어 있는 다른 리소스를 가리키는 기능을 해주기 때문이다. 아래 그림에서는 이전 게시물이 아티클 슬래시1로 되어 있고, 그 다음 URL는 아티클 슬래시3이라는 정보를 표현을 해주었다. 또한 이 정보는 링크헤더가 이미 표준으로 문서가 나와있기 때문에 이 메세지를 보는 사람이 온전히 해석을해서 링크가 어떻게 되어 있는지 이해하고 링크를타고 다른 상태로 전이가 가능하다.

그러면 왜 유니폼 인터페이스를 해야하냐.

독립적 진화라는 개념 때문이다. 이것은 무엇이냐면 아래와 같다. 서버와 클라이언트가 각각 독립적으로 진화한다는 개념인데 서버의 기능이 변경되어도 클라이언트를 업데이트 할 필요가 없다는 뜻이다. 이런 독립적 진화라는 개념이 바로 REST를 만들게 된 계기( “how do i improve HTTP without breaking the web”)에 부합한다.

다시말해서 REST가 목적으로 하는 바가 다음과 같다. 독립적인 진화. 독립적인 진화가 발생하기 위해서는 유니폼 인터페이스가 반드시 만족되어야 한다. 그래서 유니폼 인터페이스를 만족하지 못하면 REST라고 말 할수 없는 것이다.

그러면 실제로 REST가 잘 지켜지고 있는가에 대한 사례는 바로 웹이다. 우리가 사용하고 있는 웹페이지들은 REST를 매우 잘 만족하고 있다.

1) 웹 페이지가 변경되었다고 웹 브라우저를 업데이트 할 필요가 없다.

2) 웹 브라우저를 업데이트했다고 웹 페이지를 변경할 필요가 없다.

3) HTTP 명세가 변경되어도 웹은 잘 작동한다.

4) HTML 명세가 변경되어도 웹은 잘 동작한다.

물론 가끔 웹브라우저 종류나 버전, 휴대폰 단말기 제품 및 운영체제별로 같은 소스지만 페이지가 조금 화면이 깨지는 증상이 나타나곤 한다. 그러나 이런 상황이어도 기능으로써는 최소한 동작은 한다.

우리가 만드는 모바일 앱은 반면에 여러 버그 문제가 있다. 웹에서는 웹사이트가 바뀌었다고 나의 웹브라우저를 업데이트 할 필요는 없는데 모바일 앱에서는 서비스 변경 내용에 대해 업데이트를 해줘야 한다. 이말은 엄밀히 말하면 우리가 만든 모바일 서비스의 클라이언트와 서버가 REST로 통신하고 있지 않다. REST 아키텍처를 따르고 있지 않다는 것이다.
그러면 웹은 왜 이런문제가 없는 것일까. W3C Working groups(HTML 만든 사람들), IETF Working groups(HTTP 만든 사람들), 웹 브라우저 개발자들, 웹 서버 개발자들 이런 사람들의 노력 덕분이다. 그러면 어떤 노력을 하냐. HTML5 첫 초안에서 권고안이 나오는데까지 6년, HTTP/1.1 명세 개정판 작업기간 7년 이라는 시간을 보면 알 수 있다. 인터넷 동작 간에 문제가 생기지 않을까, 하위호환성을 절대로 breaking하지 않는 방법이 무엇일까라는 수많은 토론과 노력들이 있었기 때문에 가능한 것이다.
그들의 상호운영성에 대한 집착

1) Referer 오타지만 안고침 => 고치는 순간 상호운영성이 한번에 무너짐

2) charset 잘못 지은 이름이지만 안고침 => 고치는 순간 상호운영성이 한번에 무너짐

3) HTTP 상태코드 416 포기함(I’m a teapot)

최근에 HTTP 상태코드가 하나씩 추가되고 있었고 416 상태코드를 추가하려고 하는데 누가 만우절에 416 구현체를 잘못 만들어놨고 이걸 건드는 순간 전세계에 416을 어쨌든 구현체로 알고 있는 것에 대한 상호운영성이 깨지게 된다. 그래서 그냥 416번은 결번으로 하고 건너 뛰었다.

4) HTTP/0.9 아직도 지원함(크롬, 파이어폭스)

크롬에서 HTTP/0.9 버전이 구버진이기 때문에 제거하려고 시도했었으나 일부 아주 소수 프록시에서 0.9를 지원안했더니 오동작하는게 식별되었기 때문에 포기했다.

이런 노력이 없었으면 모바일 앱에서 발생하는 잡다한 오류들이 웹에서도 발생했을 것이다.

그렇다면 REST가 웹의 독립적 진화에 도움을 주었을까.

REST는 실제로 HTTP에 지속적으로 영향을 주었다. 예를 들어서 Host 헤더를 추가하게 된 것은 REST 철학의 영향을 받은 것이다. 길이 제한을 다루는 방법이 명시되는 것도 REST의 영향을 받은 것이다. URL에서 리소스의 정의가 추상적으로 변한것도 “식별하고자 하는 무언가”라는 REST 의 영향을 받은 것이다. 그 외에 HTTP와 URL에 영향을 많이 주었다. 그래서 HTTP/1.1 명세 최신판에서는 REST에 대한 언급이 수록되었다. 예를들어서 HTTP에서 representation에 대한 개념은 REST에서 온것이다 라고 되어있고 링크로 로이필딩의 REST 박사학위 논문이 걸려있다. HTTP나 URL을 만드는 사람들이 REST에 감명을 받아서 이렇게 했을수도 있는데 사실은 로이필딩이 HTTP와 URL 명세의 저자중 한명이기 때문이다.

그러면 REST가 성공했는가

REST는 웹의 독립적 진화를 위해 만들어졌고, 웹은 실제로 독립적으로 진화하고 있기 때문에 성공했다고 말 할수 있다.

그런데 REST API는?

REST API는 REST 아키텍처 스타일에 따라야 하지만 아까도 언급했듯이 오늘날 스스로 REST API라고 하는 API의 대부분이 REST 아키텍처 스타일을 따르고 있지 않다.

REST API도 저 제약조건들을 다 지켜야 하는건가? 몇개의 요소는 그냥 안지켜도 상관없지 않을까?

로이필딩은 “응 지켜야해”라고 강조했다. 그리고 “REST API는 하이퍼텍스트를 포함한 Self-descriptive한 메세지의 uniform interface를 통해 리소스에 접근하는 API” 라고 확인사살까지 해줬다.

2004년 사람들의 편견을 다시한번 집어보자

SOAP는 복잡하고, 규칙많고, 어렵다. 그러나 REST는 단순하고 규칙이 적고 쉬운것이다. 그래서 사람들은 REST를 쓰자는데 대부분의 의견이었다.

그러나 사실은 오해였다. REST도 어렵고 SOAP도 어려운 것이다.

그러면 우리가 만드는 원격 API가 꼭 REST API여야 하는건가? 만들기 어려우니까 REST API가 아니라 다른형태로 하면 안되나?

로이필딩은 REST API가 아니어도 상관없다고 한다. 그리고 “시스템 전체를 통제할 수 있다고 생각하거나, 진화에 관심이 없다면, REST에 대해 따지느라 시간을 낭비하지마”라고 했다. 시스템 전체를 통제할 수 있다는 말은 무슨말이냐면 회사에서 예를들어 서버개발자가 클라이언트 개발자의 개발업무 등을 통제할 수 있다는 것이다. 아니면 서버개발자가 서버랑 클라이언트까지 다 만드는 경우를 말한다. 이런경우에 굳이 REST를 안따라도 된다는 것이다.

진화에 관심이 없다는 말은 사용자의 요구조건을 일일히 전부 받아드리고 발전시켜 나가는 의지가 없다는 말과 같다. 오랜시간에 걸쳐 진화하는 시스템을 만들고 싶다는 것은 REST에 관심이 많다는 것과 동일하다.

그러면 우리의 옵션은?

1) REST API를 구현하고 REST API라고 부른다.

2) REST API 구현을 포기하고 HTTP API라고 부른다.

3) REST API가 아니지만 REST API라고 부른다. (대부분의 수많은 자칭 REST API라고 부르는 것들)

로이필딩이 3)을 보고 “제발 제약조건을 따르던지 아니면 다른단어르 써라” 라고 호소할 정도이다.

그러면 진짜 REST API를 만들고 싶은데 일단 왜 API는 REST가 잘 안되나 알아보자. 먼저 일반적인 웹과 비교를 해보자.

우리는 알 수 있다. 문제는 미디어 타입이구나

HTML과 JSON을 비교해보자

불완전(어떻게 파싱은해라, 문법은 어떻게 해라 정의되어 있는데 그 안에 들어가있는 값들이 어떤 정의를 가진다는 것은 명세되어 있지 않다.)

불완전하다는 것은 다시말해 문법 해석은 가능하지만 의미를 해석하려면 별도로 문서(API 문서 등) 필요하다는 것이다.

예를 들어보자 TODO 리스트에 대한것을 HTML과 JSON으로 각각 구현해보았다.

HTML은 self-descriptive(이 소스의 메세지만 보고 온전히 해석이 가능한가)한가

1) 응답 메세지의 connect-type을 보고 미디어 타입이 text/html 임을 확인한다.

2) HTTP 명세에 미디어 타입은 IANA에 등록되어 있다고 하므로, IANA에서 text/html의 설명을 찾는다.

3) IANA에 따르면 text/html의 명세는 http://www.w3.org/TR/html 이므로 링크를 찾아가 명세를 해석한다.

4) 명세에 모든태그의 해석방법이 구체적으로 나와 있으므로 이를 해석할 수 있다.

그러므로 HTML은 self-descriptive하다!

HATEOAS 측면에서 봐도 a 테그를 이용해 표현된 링크를 통해 다음 상태로 전이될 수 있으므로 HATEOAS를 만족한다.

JSON은 self-descriptive(이 소스의 메세지만 보고 온전히 해석이 가능한가)한가

1) 응답 메세지의 connect-type을 보고 미디어 타입이 application/json 임을 확인한다.

2) HTTP 명세에 미디어 타입은 IANA에 등록되어 있다고 하므로, IANA에서 application/json의 설명을 찾는다.

3) IANA에 따르면 application/json의 명세는 draft-ietf-jsonbis-rjc7159bis-04 이므로 링크를 찾아가 명세를 해석한다.

4) 명세에 json 문서를 파싱하는 방법이 명시되어 있으므로 파싱에 성공한다. 그러나 ‘id’가 무엇을 의미하고, ‘title’이 무엇을 의미하는지 알 방법이 없다.

결론적으로 온전한 해석에 실패하여 self-descriptive하다고 할 수 없다!

HATEOAS 측면에서 보면 다음상태로 전이할 링크가 아예 없기 때문에 HATEOAS도 실패한다.

그런데 여기서 self-descriptive와 HATEOAS가 독립적 진화에 어떻게 도움이 되는 것일까 의문이 생긴다.

self-descriptive = 확장 가능한 커뮤니케이션 = 서버나 클라이언트가 변경되더라도 오고가는 메세지는 언제나 self-descriptive하므로 언제나 해석이 가능하다.

HATEOAS = 어플리케이션 상태 전이의 late binding = 어디서 어디로 전이가 가능한지 미리 결정되지 않는다. 어떤 상태로 전이가 완료되고 나서야 그 다음 전이될 수 있는 상태가 결정된다. 다시말해서 특정링크에 따라 어떤 링크로 가서 하이퍼링크를 확인하고 나서야 그때서야 확정이 된다. 즉, 링크는 동적으로 변경될 수 있다.(링크들을 마음대로 바꿀 수 있다. 서버가 링크를 임의로 바꿔도 클라이언트의 동작에 문제없다.)

그러면 위의 JSON을 REST API로 고쳐보자

방법 1) 미디어 타입을 바꾼다.

미디어 타입을 정의한다. 그리고 미디어 타입 문서를 작성한다. 이 문서에 ‘id’가 뭐고 “title’이 뭔지 의미를 정의한다. 그 다음에 IANA에 미디어 타입 문서를 미디어 타입 명세로 등록한다. 그러면 이제 이 메세지를 보는 사람은 명세를 찾아갈 수 있으므로 이 메세지의 의미를 온전하게 해석할 수 있다.

단점은 매번 미디어 타입을 정의하고 등록해야 하기 때문에 상당히 번거롭다.

방법 2) 프로필을 이용