[부스트코스] Rest API와 Web API

API란?

API는  Application Programming Interface의 약자이다.

wiki를 보면 API에 대한 설명이 다음과 같이 되어 있다.

“API(Application Programming Interface, 응용 프로그램 프로그래밍 인터페이스)는 응용 프로그램에서 사용할 수 있도록, 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스를 뜻한다.

주로 파일 제어, 창 제어, 화상 처리, 문자 제어 등을 위한 인터페이스를 제공한다.

 

java 8의 API문서를 예로 들면,

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

자바 프로그래밍을 위해서는 자바 언어가 제공하는 것들이 어떤 것이 있는지를 알아야 사용할 수 있다.

예를 들어, 절대값을 구하는 코드를 작성해야한다면,

Java API문서를 통해 Math클래스의 abs()메소드를 사용하면 된다는 것을 알 수 있다.

해당 메소드가 어떻게 내부적으로 구현되어 있는지는 문서를 봐도 알 수 없다.

하지만, 해당 라이브러리를 사용할 때 구현코드를 알지 못해도 인터페이스만 알면 사용할 수 있다.

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

 

 

REST API란?

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

REST API란 말 그대로 REST형식의 API를 말한다.

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

 

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

 

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

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

이를 매시업(Mashup)이라고 한다.

 

 

이것은 REST가 아니다.

이렇게 REST API가 널리 사용되었지만, REST를 논문으로 최초 소개한 로이필딩은 대부분의 REST API라고 하는 것들이 REST 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에서 제공하는 것은 쉽지 않다.

 

 

Web API란?

REST의 uniform interface를 지원하는 것은 쉽지 않기 때문에, 많은 서비스가 REST에서 바라는 것을 모두 지원하지 않고 API를 만들게 된다. REST API의 모든 스타일을 구현하지 못할 경우에는 Web API 혹은 Http API라고 부른다.

Web API 디자인 가이드

- URI는 정보의 자원을 표현해야 한다.

- 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

 

URI는 정보의 자원을 표현해야 한다.

- GET /members

위의 표현은 멤버의 모든 정보를 달라는 요청이다.

 

- GET /members/delete/1

GET은 정보를 요청할 때 사용한다. 위와 같이 동사로 삭제를 표현하면 안된다.

 

- DELETE /members/1

HTTP Method 중의 하나만 DELETE를 이용하여 삭제를 표현해야 한다.

 

• GET /members/1                   (o)
• GET /members/get/1             (x)
• GET /members/add                 (x)
• POST /members                       (o)
• GET /members/update/1        (x)
• PUT /members/1                     (o)
• GET /members/del/1               (x)
• DELETE /members/1               (o)

 

슬래시 구분자(/)는 계층을 나타날 때 사용

http://domain/house/apartments -> 모든 집 중 아파트인 것을 요청

http://domain/departments/1/employees -> 모든 부서 중 1번 부서에 속한 사원들을 요청

 

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

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

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

- URI 경로는 소문자만 사용한다. RFC 3986(URI문법형식)은 URI스키마와 호스트를 제와하고는 대소문자를 구별한다.

- 파일 확장자는 URI에 포함시키지 않는다. Accept Header를 사용한다.

 

 

상태 코드 (성공)

- 200번 대는 대부분 성공을 의미

 

상태 코드(클라이언트로 인한 오류)

- 400번 대는 대부분 클라이언트로 인한 오류를 의미

 

상태 코드(서버로 인한 오류)

 

 

 

[부스트코스 관련 강의 링크]

Rest API란? - https://www.edwith.org/boostcourse-web/lecture/16740/

Web API란? - https://www.edwith.org/boostcourse-web/lecture/16741/

[LECTURE] 2) Web API란? : edwith