REST API

REST API (Representational State Transfer API)

웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식이며 요청과 응답의 메뉴판이라 할 수 있다.

 

REST API 디자인

디자인이라고 해서 뭐지?라는 생각이 들 수 있겠지만 쉽게 말해 잘 만드는 법이라고 생각하면 된다. REST API를 잘 적용하기 위한 4단계 모델을 만들었는데 이것을 REST 성숙도 모델이라 부른다.

• REST 성숙도 모델은 총 4단계(0~3단계)로 나누어진다.
• 모든 단계를 충족해야 REST API라고 부를 수 있다고 하지만 엄밀하게 3단계까지 지키기 어렵기 때문에 2단계까지만 적용해도 좋은 API 디자인이라고 한다. 이런 경우를 HTTP API라고 한다.

 

0단계 : HTTP 사용

• 0단계에서는 단순히 HTTP 프로토콜을 사용하기만 해도된다.(이 경우, 해당 API를 REST API라고 할 수는 없다.)
• 0단계는 REST API를 작성하기 위한 기본 단계이며 HTTP 프로토콜을 사용하는 것이 REST API의 출발점이다.

1단계 : 개별 리소스와 통신 준수

• REST API는 웹에서 사용되는 모든 데이터나 자원(Resource)을 HTTP URI로 표현한다. (모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야 하며 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 한다는 것이 1단계의 핵심)
• 어떤 리소스를 변화시키는지 혹은 어떤 응답이 제공되는지에 따라 각기 다른 엔드포인트를 사용하기 때문에, 적절한 엔드포인트를 작성하는 것이 중요하다.
• 엔드포인트 작성 시에는 HTTP 메서드, 혹은 동사 같은 어떤 행위에 대한 단어 사용은 지양하고, 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직한 방법이다.
• 요청에 따른 응답으로 리소스를 전달할 때에도 사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환해야한다.

2단계 : HTTP 메서드 원칙 준수

HTTP 메서드를 사용할 때 몇 가지 규칙에도 유의하셔야 합니다.

• GET 메서드 같은 경우는 서버의 데이터를 변화시키지 않는 요청에 사용
• POST 메서드는 요청마다 새로운 리소스를 생성
• PUT 메서드는 요청마다 같은 리소스를 반환(매 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 한다.)
• 멱등성을 가지는 메서드 PUT과 그렇지 않은 메서드 POST는 구분하여 사용
• PUT 메서드와 PATCH 메서드도 구분하여 사용(PUT은 교체, PATCH는 수정의 용도로 사용)
• 3단계까지 무조건적으로 모두 적용해야 하는 것은 아니다.
• REST 성숙도 모델의 2단계까지 적용하면 대체적으로 잘 작성된 API라고 말하며 개발자로서 보시게 될 모범적인 API 디자인조차도 REST 성숙도 모델의 3단계까지 적용한 경우는 드물다.

3단계 : HATEOAS(Hypermedia As The Engine Of Application State) 원칙 준수

• 요청은 2단계와 동일하지만, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성
• 응답 내에 새로운 링크를 넣어 새로운 기능에 접근할 수 있도록 하는 것이 3단계의 핵심 포인트

open API

• 공공데이터에 쉽게 접근할 수 있도록 정부는 Open API의 형태로 공공데이터를 제공, 공공데이터 포털에 접속해 원하는 키워드를 검색하면, 해당 키워드와 관련된 API를 확인할 수 있다.
• 글자 그대로 누구에게나 열려있는 API 하지만 무제한으로 이용할 수 있다"라는 의미는 아니다. API마다 정해진 이용 수칙이 있고, 그 이용 수칙에 따라 제한사항(가격, 정보의 제한 등)이 있을 수 있다.
• Open API를 간단하게 경험해 볼 수 있는 대표적인 페이지는, Open Weather Map이라는 웹 사이트이다. 제한적이나마 무료로 날씨 API를 사용할 수 있다. (https://openweathermap.org/api)

API key

• API를 이용하기 위해서는 API Key가 필요, 서버의 문을 여는 열쇠라고 생각하면 된다.
• 서버를 운용하는 데에 비용이 발생하기 때문에 서버 입장에서 아무런 조건 없이 익명의 클라이언트에게 데이터를 제공할 의무는 없다.(가끔 API key가 필요하지 않은 경우도 있다.)
• API Key가 필요한 경우에는 로그인한 이용자에게 자원에 접근할 수 있는 권한을 API Key의 형태로 제공하고, 데이터를 요청할 때 API key를 같이 전달해야 원하는 응답을 받을 수 있다.