[HTTP/네트워크] REST API

코드스테이즈 41기 교육 내용을 정리하고 있습니다.
틀린 부분이 있으면 댓글로 알려주시면 감사하겠습니다.

 

🍔Rest API

---

Rest API에서 REST는 “Representational State Transfer”의 약자로 로이 필딩의 박사 학위 논문에서 웹의 장점을 최대한 활용할 수있는 아키텍쳐로써 처음 소개 되었다. 

 

로이 필딩은 HTTP 1.0에 참여하던 대학원 생인데, WEB규약을 지키면서 HTTP를 업데이트 시키는 방법에 대해 고민하다가 나온게 REST API이다.

역시 대학원생들은 무섭다

 

Rest API는 웹에서 사용되는 데이터나 자원을 HTTP URI로 표현하고, HTTP 프로톸콜을 통한 요청과 응답을 정의하는 방식을 말한다.

 

Rest API를 작성할 때는 몇가지 큐칙들이 있는데, 로이 필딩이 논문에서 제시한 Rest 방법론 보다 더 실용적으로 적용하기 위해 리차드슨은 Rest API를  잘 적용시키기 위한 4단께 모델을 만들었다.

 

앞서 이야기한 로이필딩은 이 모델의 모든 단계를 충족해야 Rest API라고 부를 수 있다고 주장했다.

대부분의 Rest API라 말하는 API들은 로이 필딩이 논문에 말한 조건과 맞지 않는다고, 트위터에 말씀하셨다.

그만큼 조건을 잘 따져서 만들어야 하는 어려운 API라는 뜻이 겠쥬?

 

실제로 3단계까지 지키기 어렵기 떄문에 2단계까지만 적용해도 좋은 API디자인 이라고 볼 수 있고, 이런 경우를 HTTP API라고 부른다.

 

🍟REST 성숙도 모델 - 0단계

Rest 성숙도 모델에 따르면, 0단계에서는 단순히 HTTP 프로토콜을 사용하기만 해도 된다. 0단계 수행 이후 해당 API는 REST API로 보긴 힘들지만 REST API를 작성하기 위한 첫걸음은 맞다.

 

허준이라는 이름의 주치의의 예약 가능한 시간을 확인하고, 어떤 특정 시간에 예약하는 상황을 예로 들어 보겠다.

위 예시에서는 HTTP 프로토콜을 사용하고 있는 것을 확인할 수 있습니다. 이렇듯 단순히 HTTP 프로토콜을 사용하는 것이 REST API의 출발점아다.

 

🍟REST 성숙도 모델 - 1단계

1단계에서는 개별 리소스(Resource)와의 통신을 준수해야 한다.

모든 자원은 개별 리소스에 맞는 엔드포인트를 사용해야하며 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 한다.

 

위 예시는 요청 엔드포인트로 /appointment를 사용했다. 하지만 1단계에서는 요청하느 리소스가 무엇인지에 따라 각기 다른 엔드포인트로 구분아혀 사용해야합니다.

위의 예시에서 예약 가능한 시간 확인이라는 요청의 응답으로 받게 되는리소스은 허준이라는 의사의 예약 가능한 시간대이다. 그렇기 때문에 요청 시 /doctors/허준이라는 엔드포인트를 사용한 것을 볼 수 있다. 뿐만 아니라, 특정 시간에 예약하게 되면, 실제 slots라는 리소스의 123이라는 id를 가진 리소스가 변경되기 때문에, 하단의 특정 시간에 예약이라는 요청에서는 /slots/123으로 실제 변경되는 리소스를 엔드포인트로 사용하였다.

 

요청에 따른 응답으로 리소스를 전달할 때에도 사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환해야 한다. 예를 들어, 김코딩 환자가 허준 의사에게 9시에 예약을 진행하였으나 해당 시간이 마감되어 예약이 불가능하다고 가정할 때, 아래와 같이 리소스 사용에 대한 실패 여부를 포함한 응답을 받아야 한다.

 

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

 

🍟REST 성숙도 모델 - 2단계

REST 성숙도 모델 2단계에서는 CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둔다.

 

예약 가능 시간을 확인 한느 경우는 GET을 사용하고, 예약을 생강하는 경우 POST를 사용한다.

 

예약 가능 시간과 예약을 하는 경우 두 경우다 POST를 사용 했던 1단계와는 차이가 있어보입니다!

 

• GET 메서드 같은 경우는 서버의 데이터를 변화시키지 않는 요청에 사용해야 합니다.
• POST 메서드는 요청마다 새로운 리소스를 생성하고 PUT 메서드는 요청마다 같은 리소스를 반환합니다. 이렇게 매 요청마다 같은 리소스를 반환하는 특징을 멱등하다고 합니다. 그렇기 때문에 멱등성을 가지는 메서드 PUT과 그렇지 않은 메서드POST는 구분하여 사용해야 합니다.
• PUT 메서드와 PATCH 메서드도 구분하여 사용해야 합니다. PUT은 교체, PATCH는 수정의 용도로 사용합니다.

앞에서 말한 것 처럼 2단계까지 적용하면 잘 작성된 API라고 볼수 있다.

물론 로이필딩 아저씨에게 2단계 까지 적용한 API를 보여드리며 "REST API애오 헤헤"하면 트위터로 욕을 먹는다.

로이필드는 2단계 까지 적용된 API는 HTTP API라 불러야 한다 선을 그었다.

 

코드스테이츠에서는 앞으로 보게될 모범적인 API디자인들조차 REST 성숙도 모델 3단계 까지 적용되는 경우는 적다고 말한다. 따라서 3단계까지 무조건 적용될 필요는 없다고 말했다.

 

🍟REST 성숙도 모델 - 3단계

마지막 단계는 HATEOAS(Hypertext As The Engine Of Application State)라는 약어로 표현되는 하이퍼미디어 컨트롤을 적용합니다. 로이필딩은 Rest API라면 반드시 Hypertext-driven이어야 한다 말한다. 그만큼 Rest API를 명확하게 구분짓는 조건은 HATEOAS의 원칙을 준수하는 것이다.

 

이전과 다르게 응답에 링크 요소를 삽입 해야 작성해야하는데. 응답에 들어가는 링크요소는 응답을 받은 다읍에 할 수 있는 다양한 액션들을 위한 하이퍼미디어 컨트롤을 포함하고 있다.

예를 들어 위와 같이 허준이라는 의사의 예약 가능 시간을 확인한 후에는 그 시간대에 예약을 할 수 있는 링크를 삽입하거나, 특정 시간에 예약을 완료하고 나서는 그 예약을 다시 확인할 수 있도록 링크를 작성해 넣을 수도 있다.

이렇게 응답 내에 새로운 링크를 넣어 새로운 기능에 접근할 수 있도록 하는 것이 3단계의 핵심이다.

 

만약 클라이언트 개발자들이 응답에 담겨 있는 링크들을 눈여겨본다면, 이러한 링크들은 조금 더 쉽고, 효율적으로 리소스와 기능에 접근할 수 있게 하는 요소가 될 수 있다.