REST API란

API란

REST API에 대해 설명하기 전, 기본적으로 API는 무엇인지에 대해 알아야 한다.

API

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

예를 들어 회사에서 사용하려고 파일 제어(관리)하는 응용프로그램을 만들었다고 생각해보자.

회사 내부에서는 문제가 되지 않지만 외부 사용자가 해당 프로그램을 사용하려고 할 때, 외부 사용자가 해당 소스 및 데이터베이스에 접근하면 안된다.

이런 문제를 해결하기 위해서 API가 사용하는 것이다.

API를 통해 소스 및 데이터베이스는 접근하지 못하게하고 해당 프로그램을 사용할 수 있도록 기능을 제공하는 것이다.

보통 웹에서의 API는 데이터를 요청하고 응답하는게 전부이며, Wiki에서는 웹API를 아래와 같이 정의해 놓았다.

"웹 API는 웹 애플리케이션 개발에서 다른 서비스에 요청을 보내고 응답을 받기 위해 정의된 명세를 일컫는다."

SOAP

http://www.slideshare.net/seunghochoi4/soap-restful

REST API란

REST API

Representational State Transfer (표현 상태 전이, REST)

REST API는 크게 리소스, 메서드, 메세지로 이루어져 있다. 

예, "이름이 Terry인 사용자를 생성한다."라는 호출이 있을 때, 

- 리소스: "사용자" -> http://myweb/users라는 형태의 URI

- 메서드: "생성한다"라는 행위 -> HTTP POST 메서드

- 메세지: "이름이 Terry인 사용자" -> 생성하고자 하는 사용자의 디테일한 내용은 JSON 문서를 이용해서 표현

HTTP POST, http://myweb/users/
{
    "users": {
        "name": "terry"
    }
}

REST Architecture 6가지 원칙 (RESTful)

- 균일한 인터페이스 Uniform interface

- 상태없음 Stateless

- 캐시 Cache

- 클라이언트/서버 Client/Server

- 계층 시스템 Layered system

- (조건부) Code on demand

URI

REST API는 리소스를 나타낼 때 URI(Uniform Resource Identifier)를 사용한다. 

URI는 "http://api.example.restapi.com/kfootball/news"처럼 분명하게 표현된 것들부터 사람이 이해하기 힘든 "http://api.example.restapi.com/23444-122dds-dfsee"와 같은 것까지 다양하게 사용된다.

URI 형태

1. 슬래시(/)는 계층 관계를 나타내는 데 사용된다.

포워드 슬래시(/)는 경로내에서 리소스 간의 계층 관계를 나타내는 데 사용된다.

http://api.example.restapi.com/kfootball/news

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

URI 경로 마지막에 있는 슬래시는 아무런 의미가 없지만, 혼란을 방지하기 위해 REST API의 마지막 글자에 슬래시를 포함해서는 안된다.

많은 웹 컴포넌트와 프레임워크에서는 다음 두 URI를 같은 것으로 취급한다.

http://api.example.restapi.com/kfootball/

http://api.example.restapi.com/kfootball

하지만 URI는 유일한 리소스 식별자로 사용되기 때문에 REST API는 분명한 URI를 만들어 통신해야 한다. 규칙을 엄격하게 적용하지 않은 API들은 클라이언트가 보낸 URI를 마지막에 슬래시(/)가 없는 URI로 리다이렉트하기도 한다.

3. 하이픈(-)은 URI 가독성을 높이는데 사용된다.

URI를 쉽게 이해하기 위해, 긴 URI에 하이픈(-)을 사용해서 가독성을 높일 수 있다.

http://api.example.restapi.com/blogs/my/first-post

4. 밑줄(_)은 사용하지 않는다.

텍스트 뷰어 애플리케이션은 클릭할 수 있다는 표시로 URI에 밑줄을 긋는다. 또한, 글꼴에 따라 밑줄은 보기 어렵거나 문자가 완전히 가져지기도 한다.

밑줄로 URI를 표현하는 대신 하이픈(-)을 사용해야 한다.

5. URI는 소문자로 구성하는게 적합하다.

RFC 3986은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정한다.

1. http://api.example.restapi.com/blogs/my/first-post
2. HTTP://API.EXAMPLE.RESTAPI.COM/blogb/my/first-post
3. http://api.example.restapi.com/blogs/My/First-Post

URI 스펙(RFC 3986)에 따라 1번과 2번은 같은 것으로 간주되며 3번은 1,2와 다른 URI를 나타낸다. 이러한 혼란을 피하기 위해 기본적으로 URI는 소문자로 구성한다.

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

웹에서 점(.)은 URI에서 파일 이름과 확장자를 구분하는데 사용된다.하지만 REST API는 미디어 타입에 의존하여 Content-Type 헤더를 통해 전달되고 메세지 바디의 내용을 어떻게 처리할지 결정한다.

URI 권한 설계

1. API에 있어서 서브 도메인은 일관성있게 사용돼야 한다.

API 최상위 도메인과 1차 서브 도메인 이름(예, map.daum.net)으로 서비스를 제공해야 한다. API의 전체 도메인 이름에 api라는 서브 도메인을 붙여야 한다.

http://apis.map.daum.net/

2. 클라이언트 개발자 포탈 서브 도메인은 일관성있게 사용돼야 한다.

보통 REST API는 개발자 포탈이라는 개발자들을 위한 웹 사이트를 제공한다. 이 포탈은 웹 사이트의 문서 등을 포탈에서 직접 제공하는 API를 이용하여 새로운 클라이언트를 개발할 수 있도록 도와준다. 관습적으로 이러한 웹 사이트의 URI는 developers라는 서브 도메인을 사용한다.

https://developers.daum.net/services

메서드

REST에서는 HTTP 메서드를 그대로 사용한다. HTTP에서 여러 메서드가 있지만 REST API에서는  CRUD(Create Read Update Delete)에 해당하는 네가지 메서드를 사용한다.

• POST: 등록 (Create)
• GET: 조회 (Select/Read)
• PUT: 수정 (Update)
• DELETE: 삭제 (DELETE)

CRUD 네가지 상황 외에 컨트롤러를 실행하는데 POST 메서드가 사용된다. POST 요청 메시지는 파라미터 정보를 헤더나 바디에 포함시킬 수 있다.

또한, 최근에는 PATCH라는 메서드를 많이 사용하고 있다. PUT이 해당 자원의 전체를 수정하는 의미하며, PATCH는 해당 자원의 일부를 수정한다는 의미로 인해 update 이벤트에서 PUT보다는 PATCH가 더 적합하다고 평가받고 있다.