#02. BE - Rest API

<2. DB 연결 웹 애플리케이션 - Rest API>

http://www.edwith.org/boostcourse-web

클라이언트의 종류가 웹 브라우저, 안드로이드 앱, iOS 앱 등 다양해지면서 이러한 클라이언트들에게 정보를 제공하는 방식을 하나로 일원화시키고 싶어졌다. 일원화시키는 방식 중에 대표적인 방식이 HTTP프로토콜로 API를 제공하는 것이다.

=> HTTP프로토콜로 제공하는 API를 REST API라고 한다.

* API란?

API는  Application Programming Interface의 약자이다.

* wiki에 나와있는 API에 대한 설명

API(Application Programming Interface, 응용프로그램 프로그래밍 인터페이스)는 응용 프로그램에서 사용할 수 있도록, 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스이다. 주로 파일 제어, 창 제어, 화상 처리, 문자 제어 등을 위한 인터페이스를 제공한다.

참고 바로가기

자바 언어가 제공하는 클래스와 인터페이스에 대한 설명이 API문서이다.

자바 프로그래밍을 위해서는 자바 언어가 제공하는 것들이 어떤 것이 있는지를 알아야 하며, 이것은 Java API문서를 읽어보면 알 수 있다. 해당 메소드가 어떻게 내부적으로 구현되어 있는지는 문서를 봐도 알 수 없으나 해당 라이브러리를 사용할 때 구현코드를 알지 못해도 인터페이스만 알면 사용할 수 있다.

이렇게 프로그래밍을 할 때 필요한 인터페이스를 API라고 한다.

---

* REST API란?

• REST는 REpresentational State Transfer라는 용어의 약자로서 2000년도에 로이 필딩 (Roy Fielding)의 박사학위 논문에서 최초로 소개되었다.

• REST API란 말 그대로 REST형식의 API이다.

• REST API란 핵심 컨텐츠 및 기능을 외부 사이트에서 활용할 수 있도록 제공되는 인터페이스이다.

네이버에서 블로그에 글을 저장하거나, 글 목록을 읽어갈 수 있도록 외부에 기능을 제공하거나 우체국에서 우편번호를 조회할 수 있는 기능을 제거하거나, 구글에서 구글 지도를 사용할 수 있도록 제공하는 것들을 말한다.

• 웹 브라우저 뿐만 아니라 앱 등 다양한 클라이언트가 등장하면서 그러한 클라이언트들에게 대응하기 위해 REST API가 널리 사용되기 시작했다.

• 서비스 업체들이 다양한 REST API를 제공함으로써, 클라이언트는 이러한 REST API들을 조합한 어플리케이션을 만들 수 있게 되었다. 이를 매시업(Mashup)이라고 한다.

* 유명 사이트에서 제공하는 API 관련된 문서 링크

네이버 API 소개

페이스북의 그래프 API 문서

공공 데이터 포털

---

* REST가 반드시 지켜야 하는 스타일

• client-server (클라이언트-서버 구조)

• stateless (무상태성)

• cache (캐시 가능)

• uniform interface (유니폼 인터페이스)

• layered system

• code-on-demand (optional)

여기서 스타일이란 제약조건의 집합을 의미한다. 위에서 언급한 내용을 잘 지켜야만 REST라고 말할 수 있다.

HTTP프로토콜을 사용한다면 client-server, stateless, cache, lared system, code-on-demand 등에 대해서는 모두 쉽게 구현 가능하다. 하지만, 문제는 uniform interface이다.

* uniform interface의 스타일

• 리소스가 URI로 식별 돼야한다.

• 리소스를 생성, 수정, 추가하고자 할 때 HTTP메시지에 표현을 해서 전송해야 한다.

• 메시지는 스스로 설명할 수 있어야 한다. (Self-descriptive message)

• 애플리케이션의 상태는 Hyperlink를 이용해 전이되어야 한다.(HATEOAS)

첫 번째와 두 번째 항목은 지키기 어렵지 않은데, 메시지가 스스로 설명할 수 있어야 하는 부분과 HATEOAS를 지원하는 것은 웹과는 다르게 API로는 쉽지가 않다.

응답 결과에 보통 JSON 메시지를 사용하게 되는데, 이 JSON메시지가 어디에 전달되는지와 JSON메시지를 구성하는 것이 어떤 의미를 표현해야만 메시지 스스로 설명할 수 있다고 말할 수 있는지가 쉽지 않기 때문이다.

우리가 웹 게시판을 사용할 때 리스트 보기를 보면 상세보기나 글쓰기로 이동할 수 있는 링크가 있다. 상세보기에서는 글 수정이나 글 삭제로 갈 수 있는 링크가 있다. 이렇게 웹 페이지를 보면, 웹 페이지 자체에 관련된 링크가 있는것을 알 수 있는데 이를 HATEOAS라고 말한다.

이런 HATEOAS를 API에서 제공하는 것 또한 쉽지 않다.

1) 리소스가 URI로 식별 돼야 한다.

GET /members/delete/1 (X)

위와 같은 방식은 REST를 제대로 적용하지 않은 URI이다. URI는 자원을 표현하는데 중점을 두어야 하므로 delete와 같은 행위에 대한 표현이 들어가서는 안 된다.

2) 리소스를 생성, 수정, 추가하고자 할 때 HTTP메시지에 표현을 해서 전송해야 한다. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)로 표현한다.

DELETE /members/1 (O)

3) 슬래시 구분자(/)는 계층을 나타낼 때 사용한다.

http://domain/houses/apartments (O)

http://domain/departments/1/employees (O)

4) URI 마지막 문자로 슬래시 구분자(/)를 포함하지 않는다.

http://domain/houses/apartments/ (X)

5) 하이픈(-)은 URI 가독성을 높일 때 사용한다.

6) 언더바(_)는 사용하지 않는다.

7) URI경로는 소문자만 사용한다.

8) RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별한다.

9) 파일 확장자는 URI에 포함하지 않는다.

http://restapi.example.com/members/soccer/345/photo.jpg (X)

10) Accept Header를 사용한다.

- HTTP METHOD의 알맞은 역할 

• POST: POST를 통해 해당 URI를 요청하면 리소스 생성
• GET: GET을 통해 해당 리소스 조회. 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져온다.
• PUT: PUT를 통해 해당 리소스 수정
• DELETE: DELETE를 통해 리소스 삭제

[참고] http://meetup.toast.com/posts/92

* Web API, 혹은 HTTP API를 사용

REST의 uniform interface를 지원하는 것은 쉽지 않기 때문에, 많은 서비스가 REST에서 바라는 것을 모두 지원하지 않고 API를 만들게 된다.

=> 이럴 경우 Web API혹은 HTTP API라고 부른다.

• REST의 모든 것을 제공하지 않으면서 REST API라고 말하는 경우도 있음

• REST의 모든 것을 제공하지 않고 Web API 혹은 HTTP API라고 부르는 경우가 있음