REST API

# REST API

-웹에서 사용되는 데이터나 자원(resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식

- API의 대표적인 아키텍처이다.

- rest는 “Representational State Transfer”의 약자

 

# 로이필딩 REST 방법론 -> 레오나르드 리차드슨(Leonard Richardson) REST 성숙도 모델

 

# REST성숙도모델

- 총4단계(0~3단계)

- 로이필딩은 모든 단계를 충족해야 REST API라고 부를수있다고 주장.
실제로는 2단계까지만 적용해도 좋은 API디자인이다. HTTP API라고 부른다.

---

< REST성숙도모델 - 0단계 >

#단순히 HTTP프로토콜을 사용하기만 해도된다.
-이경우 해당 API를 REST API라고 할수없다.

#0단계는 REST API를 작성하기 위한 기본단계이다.

---

< REST성숙도모델 - 1단계 >

#개별 리소스(resource)와의 통신을 준수해야한다.
-모든 자원(resource)은 개별 리소스에 맞는 엔드포인트를 사용해야하며 요청하고 받는 자원에 대한 정보를 응답으로 전달해야한다는것이 1단계의 핵심이다.

 

#0단계에서는 요청에서의 엔드포인트로 모두 /appointment를 사용하였다.

-1단계에서는 요청하는 리소스가 무엇인지에 따라 각기 다른 엔드포인트로 구분하여 사용한다.

-어떤 리소스를 변화시키는지 혹은 어떤 응답이 제공되는지에 따라 각기 다른 엔드포인트를 사용하기 때문에, 적절한 엔드포인트를 작성하는 것이 중요하다

-엔드포인트 작성시에는 동사, HTTP메서드, 혹은 어떤 행위에 대한 단어 사용은 지양하고 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직하다.

 

#요청에 따른 응답으로 리소스를 전달할때에도 사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환해야 한다. (리소스 사용에 대한 성공/실패 여부를 포함한 응답을 받아야한다)

 

-예약가능한 시간확인 요청시 /doctors/허준 이라는 엔드포인트를 사용함
-특정시간에 예약 요청시 /slots/123 를 엔드포인트로 사용함

-리소스 사용에 대한 실패여부를 포함한 응답을 받았다 ("해당시간은 이미 예약되어있습니다")

---

< REST성숙도모델 - 2단계 >

#CRUD에 맞게 적절한 HTTP메서드를 사용하는 것에 중점을 둔다.
-0단계와 1단계 예시에서는 모든 요청을 CRUD와 상관없이 POST 메서드를 사용했다.

#HTTP메서드 사용시 아래규칙에 유의해야한다
-get메서드: 서버의 데이터를 변화시키지 않는 요청에 사용해야한다.
-post메서드: 요청마다 새로운 리소스를 생성
-put메서드는 요청마다 같은 리소스를 반환

멱등성을 가지는 put과 그렇지 않은 post를 구분하여 사용해야한다.

(*멱등 idempotent: 매요청마다 같은 리소스를 반환하는 특징)

-put, patch메서드도 구분하여 사용해야한다. put은 교체, patch는 수정의 용도로 사용한다.

#REST 성숙도 모델의 2단계까지 적용하면 잘 작성된 API이다.
로이필딩은 3단계까지 만족하지 못한 API는 REST API가 아닌 HTTP API라고 불러야한다고 주장.

 

---

< REST성숙도모델 - 3단계 >

#3단계의 포인트!
-응답 내에 새로운 링크를 넣어 새로운 기능에 접근할수있도록 하는것!

#HATEOAS(Hypermedia As The Engine Of Application State)라고 표현하는 하이퍼미디어 컨트롤을 적용한다.

 

#3단계의 요청은 2단계와 동일
응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야한다.
응답에 들어가게 되는 링크 요소는 응답을 받은 다음에 할수있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있다.