[Codestates] REST API

REST API

REST API는 로이 필딩 (Roy Fielding)의 박사학위 논문에서 웹의 장점을 최대한 활용하는 아키텍쳐로 제안되었다. 오늘날 REST API는 큰 성공을 거뒀으며, 대부분 JSON을 통신 형식으로 한다.

HTTP 프로토콜을 사용하여 요청과 응답을 정의하는 방식으로, 웹에서 사용하는 데이터나 리소스를 HTTP URI 형식으로 표현한다.

REST API를 더 효율적으로 사용하기 위해 레오나르드 리차드슨 (Leonard Richardson) 이 디자인 모델을 제시했다.
이를 RMM (Richardson Maturity Model) 이라고 한다.

---

0단계에선 HTTP 프로토콜만 사용해도 된다. 이는 REST API를 작성하기 위한 가장 기본 단계다.
REST API는 웹에서 사용하는 데이터나 리소스를 HTTP URI로 표현한다.


따라서 1단계는 /appointment, 개별 리소스에 맞는 엔드 포인트를 지정해야 한다.
엔드포인트 작성 시에는 동사, HTTP 메서드, 어떤 행위에 대한 단어는 지양하고, 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직 하다.
응답으로 리소스를 전달할 때에도 사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환해야 한다.


2단계는 CRUD에 맞는 HTTP 메소드를 사용해야 한다. 응답도 메소드에 따른 올바른 응답코드를 작성해야 한다.

• GET 메소드는 서버에 데이터를 변경시키지 않는 요청을 해야 한다.
• POST 메서드는 요청마다 새로운 리소스를 생성한다. PUT 메서드는 요청마다 같은 리소스를 반환한다.
  매번 같은 리소스를 반환하는 것을 멱등(idempotent)하다고 한다.
  멱등성을 가지는 메소드와 아닌 것을 구분하여 사용한다.
• PUT은 교체, PATCH는 수정의 용도로 구분하여 사용한다.

로이 필딩은 3단계까지 모두 지켜야 REST API라고 할 수 있으며, 만족하지 못하면 HTTP API라고 불러야 한다고 한다.
그러나 RMM의 3단계까지 적용된 API는 상대적으로 모범적이라는 API에서도 드물다.
때문에 2단계까지 만족하더라도 대체적으로 잘 작성됐다고 볼 수 있다.

3단계는 HATEOAS(Hypertext As The Engine Of Application State)라는 약어로 표현되는 하이퍼미디어 컨트롤을 적용한다.
요청은 2단계와 동일하지만, 응답에 리소스에 대한 링크 요소를 삽입해 보내야 한다.
링크 요소는 응답을 받아 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함해야 한다.

---

Open API

Open API는 말그대로 열려있는 공공 API이다. 하지만 열려있다 해서 무제한적이진 않다.
이용 수칙에 따라 과금이나 정보의 제한이 있을 수 있다. API를 이용하기 위해선 API KEY가 필요하다.

제한을 두는 이유는 서버를 운용하는데는 금액이 발생하기 때문이다. 이 때문에 익명의 클라이언트들에게 무상으로 제공할 의무는 없다.