『Web API The Good Parts』를 읽고 - Web API란 무엇인가

각 개념

Web API

HTTP프로토콜을 이용해 네트워크를 통신을 하는 API를 말한다.

Web API라고 하면 SOAP(Simple Object Access Protocol)이나 XML-RPC를 떠올릴 수 있으나 이 책에서는 URI에 액세스 하면 XML이나 JSON을 반환하는 심플한 API를 다루고 있다.

API

Application Programming Interface의 약자로 외부에서 통신할 수 있도록 정한 사양을 가리킨다.

URI와 URL

URI

Uniform Resource Identifier의 약자로 인터넷 상의 자원을 나타내는 주소이다.

URL

Uniform Resource Location의 약자이다. 원래 단어에서 알 수 있듯이 URL은 URI의 하위개념으로 자원의 위치를 표현한다.
예를 들어, 아래와 같은 링크에서 http부터 12345가 URL이고 http부터 search까지가 URI이다.

http://api.example.com/users/12345?from=search

X(구 트위터)의 API를 보면 아래와 같이 JSON으로 끝나는 것도 있다. 브라우저에 표시하기 위한 것이 아니라 데이터를 취득하는 것이 목적이라는 것을 알 수 있다.

https://api.twitter.com/1.1/statuses/user_timeline.json

REST

일반적으로 REST API라고 불리는 개념으로 HTTP로 접근할 수 있으며 XML이나 JSON을 반환하는 API를 가리킨다.

Web API의 중요성

이 책에서는 웹 서비스를 제공하고 있다면 무조건 API를 공개해야 한다고 주장한다. 일례로 여러 어플에서 페북 등의 SNS로 공유할 수 있게 된건 그들이 Web API를 공개한 덕분이라고 한다.

즉, 외부 서비스와 연계하기 쉬워져 새로운 가치를 만들기 쉽고 그것을 서비스나 비지니스적으로 풀어내기도 쉽다는 것이다. 이를 API이코노미 라고 한다.

보안을 걱정한다면 아래의 이유로 잊으라 한다.

• 인기가 없는 서비스라면 애초에 공격당할 가능성이 적다
• 인기가 있는 서비스라면 공격보다는 확산되는 장점이 훨씬 크다
• 공개했든 안했든 공격할 사람들은 하기 때문에 어찌됐든 보안은 철저히 해야한다

액세스 수가 너무 증가하지 않을까 걱정된다면 요즘엔 유저 당 액세스 수를 제한하거나 한도를 넘을 땐 이용료를 따로 내게끔 되어있기 때문에 괜찮다고 한다.

그리고 http://import.io/ 나 https://www.kimonolabs.com/ 과 같이 웹 페이지를 API로 변환해주는 서비스도 있다.

이미 공개한 API라면 http://programmableweb.com/ 에서 확인할 수 있다.

여러 API 패턴

최근 Web API가 중요해진 만큼 개발자도 제대로 설계해야한다. 예를 들어, 아래와 같은 상황이 있다.

• 공개 웹 서비스의 데이터 혹은 기능의 API를 공개할 때
• 다른 페이지에 첨부하는 위젯을 공개할 때
• 모던한 웹 어플리케이션을 만들 때
• 스마트폰 어플리케이션을 만들 때
• 사내 시스템을 연계할 때
• 소셜 게임을 개발할 때

API로 공개해야 하는 것

API를 공개하려는 서비스가 할 수 있는 것 전부이다. 즉, 가장 중요한 가치를 두는 기능을 전부 공개해야 한다는 것이다.

왜 설계를 잘 해야하는가

왜 아름다운 코드를 작성해야하는가와 거의 일맥상통한다. 구체적으로는 아래의 이유를 들 수 있다.

• 이용하기 쉽다
  • 개발할 때 개발자의 스트레스를 줄일 수 있다
• 변경하기 쉽다
  • 버전이 낮은 어플리케이션이 갑자기 에러나는 것을 막을 수 있다
• 뚫리기 어렵다
  • 공개했다면 누구나 접근 가능하기 때문에 보안을 고려해 개발한다
• 공개했을 때 부끄럽지 않다(외부에서 기술력을 판단하는 재료이기 때문에)

Netflix사의 API담당 엔지니어링 디렉터 Daniel Jacobson은 「(The future of API desig: The orchestration layer)[http://thenextweb.com/dd/2013/12/17/future-api-design-orchestration-layer]」에서 SSKDs(small set of known developers)와 LUSDs(large set of unknown developers)라는 표현을 썼다. 간단히 말하면 누가 사용할지가 명확한 케이스(비공개 사내 API 등)와 그렇지 않은 케이스(공개 API)가 있다는 것이다.

이러한 상황을 제대로 고려할 필요가 있다.

아름다운 Web API란

엔드포인트가 명확하고 통신 방법이 명확하고 알기 쉽고 적절한 response를 반환하면 된다.

가장 중요한 것은 아래 두가지이다.

• 사양이 정해져 있다면 그에 따른다
• 사양이 정해져있지 않다면 디팩트 스탠다드(일반적으로 그 업계에서 통용되는 표준 기준)을 따른다
  • 이 책에서 이제부터 말하고자 하는 것이 이것이다

API설계는 개발자의 기술 레벨을 측정하는 재료이기 때문에 (잘 만들었을 것이기 때문에) 타 서비스의 API를 참고하면 좋다. 선택에 선택을 거듭해 공개한 것이 이윽고 스탠다드가 되어있다면 충분히 따라야 할 이유도 있을 것이기 때문이다.
또한 다른 개발자들이 봤을 때 어느 정도 예상 가능한 것들이어야 확장 개발을 하기도 쉽고 이용하기도 쉽다.

REST와 Web API

REST의 method는 행위를 나타내니 동사인 것처럼 URI는 자원을 나타내니 명사로 끝내야 한다.

예를 들어, URI가 post/delete/1 이면 DELETE post/delete/1 이 될 것이기 때문에 삭제한다는 의미가 중복된다. post/1 정도가 적절하겠다.