RESTful Web API 설계 절차 - RESTful Web API에서 발췌

웹 서비스가 스스로 새로운 웹서비스를 만들어가는 스마트한 IoT 세상을 꿈꾸는 "생각의 웹"입니다.

웹 세상에서 REST API가 Open API의 대세로 자리 매김한지도 꽤 시간이 지났음에도

진정 RESTful API를 설계하는 일이 여전히 쉽지 않습니다.

따라서 이전에 포스트에서 REST API의 성숙도를 표현하는 리처드슨의 성숙도 모델이 있다는 것 소개드린 바 있습니다.

http://webofthink.tistory.com/2

이번 포스트에서는 REST API의 대가인 리처드슨, 아문센 그리고 샘 루비가 오레일리 출판사를 통해 작년 말에 내 놓은 RESTful Web API에서 발췌한 REST API를 설계하는 절차를 소개하려 합니다.

먼저, 발췌한 해당 내용의 스크린 샷을 이미지 슬라이드로 보여 드리죠.

012345678910111213

책에서는 API를 설계하는 서로다른 두 가지 절차를 소개합니다. 첫번째는 두 단계로 이뤄진 요약이고 두 번째는 일곱 단계로 이뤄진 상세한 내용이라고 할 수 있습니다.

전자에 대해 정리하면 다음과 같습니다.

1.  HTTP 요청에 대한 응답 body에 표현 (representation)으로 사용할 미디어 형태 (media type)을 선택한다. 이 선택으로 말미암아 프로토콜 의미 (protocol semantics) - HTTP 프로토콜 하에서 API의 동작 - 와 어플리케이션 의미 (application semantics) - 표현으로 참조할 수 있는 실제 세계의 사물 -  에 제약을 받게 된다.
   
   
2. 나머지 모든 것을 대응할 수 있는 프로파일 (profile)을 작성한다.

REST API에 대해 설계한 경험이 없다면 이 두 단계로 함축한 것으로는 이해하기가 어려울 것으로 사료됩니다. 이 책을 읽고 포스트를 작성하는 저 스스로도 잘 와닿지 않기 때문입니다. ^^;

이번에는 좀 더 상세한 단계를 설명해 주고 있는 후자에 대해서 살펴 보시죠.

1.  클라이언트(client) - REST API를 호출할 웹 앱 - 이 알아야 하거나 API에 담고자 하는 모든 정보를 나열한다. 이 정보가 추후 의미 기술 (semantic descriptors)이 되며 계층적 구조를 갖게 됩니다. 예를 들어 '사람'과 같은 오브젝트는 보다 추상적인 '성'과 같은 상세 정보를 갖게 되는데 이런 정보 간 계층이 직관적으로 묶일 수 있도록 합니다. 
   
   
2. API를 위한 상태 전이도 (state diagram)를 그립니다. 이 도식에서 칸은 하나의 표현 - 의미 기술의 일부를 함께 묶은 문서 - 을 나타냅니다. 클라이언트가 이런 표현들을 자연스럽게 찾을 수 있도록 화살표를 이용해 표시합니다. 이 화살표는 HTTP 요청에 따른 상태 전이 (state transitions)이 됩니다.
   
   
3. 의미 기술에 사용한 임의의 용어 (magic strings)를 기존 프로파일(profile)에 존재하는 용어로 대체합니다. 이때 사용한 모든 단어와 두번째 단계에서 그린 상태 전이도에 모두 적용될 때까지 반복합니다.
   
   
4. 프로토콜 의미와 어플리케이션 의미에 부합하는 (compatible) 미디어 형식 (media type)을 선정하거나 필요할 경우 새로 만듭니다. 운이 좋다면 기 정의된 미디어 형식으로 어플리케이션 의미의 상당 부분을 대응할 수 있으며 이때 세 번째 단계로 되돌아 가서 미디어 형식의 용어가 대응하는지 다시 살펴봅니다.
   
   
5. 어플리케이션 의미를 기술하는 프로파일을 작성합니다. 이 프로파일에는 당신만의 용어 (magic string), IANA에 등록된 링크 관계가 아닌 링크 관계들과 미디어 형식에 의해 기술된 용어를 담고 있어야 합니다.
   
   
6.  세번째 단계에서 도출한 상태 전이도를 HTTP 서버로 구현하기 위한 코드를 작성합니다. 클라이언트는 특정 HTTP 요청으로 상태를 전이시키게 되고 그 결과로 응답을 전송받게 됩니다. 이 응답의 표현에는 4번째 단계에서 정의한 미디어 형식과 5번째 단계에서 정의한 프로파일에 대한 링크가 포함되어야 합니다. 
   
   
7.  API를 사용하기 위한 접속 주소가 되는 빌보드 URL를 제공합니다. 또한 개발자를 위한 API 문서, 튜토리얼 및 예제 클라이언트 코드를 제공할 수도 있습니다.

API를 설계하는 일은 사용자를 고려한 UX를 설계하는 일처럼 어려운 일입니다. 특히, API를 사용하는 주체가 사람 뿐 아니라 기계일 경우는 더욱 그렇습니다.

프로그래머블 웹이 현실이 되고 인터넷에 연결된 IoT 기기가 시장에 본격적으로 등장하면서 진정 스마트한 기기를 만들기 위해서는 스마트한 API를 만들 수 있는 기술이 필요합니다.

이 설계 방법이 스마트한 웹 세계를 만들 것이라 기대해 봅니다.

감사합니다.