S2) Unit 8. [HTTP/네트워크] REST API

📣  REST(Representational State Transfer) API

✔️ 웹에서 사용되는 데이터나 자원을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식 -> 알아보기 쉽고 잘 작성된 메뉴판

➰ 클라이언트와 서버 사이에도 데이터와 리소스를 요청하고, 응답을 전달하기 위한 '메뉴판'이 필요하다.

➰ 로이 필딩이란 박사 학위 논문에서 최초로 소개되었으며, 웹 설계의 우수성에 비해 제대로 사용되지 못하는 것이 안타까워 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했다.

 

📣  REST API 디자인하는 방법

✔️ 리차드슨의 REST 성숙도 모델

➰ 실제로 3단계까지 지키기 어렵기 때문에 2단계까지만 적용해도 좋은 API 디자인 -> HTTP API 라고 부른다.

➰ 로이 필딩은 3단계까지 만족하지 못한 API는 REST API가 아닌 HTTP API라고 불러야 한다고 주장.

 

0️⃣ REST 성숙도 모델 - 0단계

✔️ 단순히 HTTP 프로토콜을 사용하기만 해도 된다.

✔️ REST API 라고 할 수 없는, REST API 를 작성하기 위한 기본 단계

➰ 위처럼 HTTP 프로토콜을 사용하기만 해도 된다.

 

1️⃣ REST 성숙도 모델 - 1단계

✔️ 개별 리소스와의 통신을 준수해야 한다.

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

➕ 엔드포인트란?

➰ 서비스를 이용할 때 사용하는 커뮤니케이션 채널의 한쪽 끝에 해당하는 URI (최종 목적지)

➰ API로 요청을 서버와 통신할 때, 서버가 요청을 수락하는 시작점

➰ 일반적으로 root-endpoint는 도메인 주소의 루트( / )를 가리킵니다.

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

➰ 예약 가능한 시간 확인이라는 요청의 응답으로 받게 되는 리소스는 허준 이라는 의사의 예약 가능한 시간대이다.

➰ 그래서 요청 시 /doctors/허준 이라는 엔드포인트를 사용했다.

➰ 또한 특정 시간에 예약을 하면 slots 리소스의 123이라는 id를 가진 리소스가 변경되기 때문에 특정 시간에 예약 요청에서는 /slots/123 으로 실제 변경되는 리소스를 엔드포인트로 사용했다.

➰ 어떤 리소스를 변화시키는지 혹은 어떤 응답이 제공되는지에 따라 각기 다른 엔드포인트를 사용해야 한다.

 

➰ 요청에 따른 응답으로 리소스를 전달할 때도 사용한 리소스에 대한 정보 + 리소스 사용에 대한 성공/ 실패 여부를 반환해야 한다.

➰ 9시에 예약을 하였으나, 이미 해당 시간이 마감되어 예약 불가능한 경우 리소스 사용에 대한 실패 여부를 포함한 응답을 받아야 한다.

 

2️⃣ REST 성숙도 모델 - 2단계

✔️ CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것이 중요하다.

➰  0, 1단계 에서는 모든 요청을 CRUD와 상관없이 POST 메서드를 사용하고 있다.

➰  2단계 에서는 예약 가능한 시간을 확인하는 것은 조회(READ), 특정 시간에 예약 한다는 것은 생성(CREATE)와 같다.

➰  때문에 조회는 GET, 생성은 POST 메서드를 사용해서 요청을 보내야 한다.

➰  GET 메서드는 body를 가지지 않기 때문에 query parameter를 사용해서 필요한 리소스를 전달한다.

➰  POST 요청의 응답은 새롭게 생성된 리소스를 보내주기 때문에, 응답 코드는 201 Created로 명확하게 작성해야 하며, 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인할 수 있도록 해야 한다.

🚨 HTTP 메서드를 사용할 때의 규칙

➰ GET 메서드 : 서버의 데이터를 변화시키지 않는 요청에 사용

➰ POST 메서드 : 요청마다 새로운 리소스를 생성

➰ PUT 메서드 : 요청마다 같은 리소스를 반환(멱등하다) -> PUT과 POST 구분해서 사용

➰ PATCH 메서드 : 수정할 때 사용 -> PATCH와 PUT 구분해서 사용

 

3️⃣ REST 성숙도 모델 - 3단계

✔️ HATEOAS(Hypermedia As The Engine Of Application State) 라는 하이퍼미디어 컨트롤를 적용한다.

✔️ 요청은 2단계와 동일하지만, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야 한다.

➰ 응답에 들어가게 되는 링크 요소는 응답을 받는 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있다.

➕ 하이퍼미디어 컨트롤이란?

➰ 정의 : 기본적인 아이디어는 하이퍼미디어를 애플리케이션의 상태를 관리하기 위한 매커니즘으로 사용한다는 것

➰ REST API 를 사용하는 클라이언트가 전적으로 서버와 동적인 상호작용이 가능하도록 하는 것

➰ 클라이언트가 서버에게 어떠한 요청을 할 때, 요청에 필요한 URI를 응답에 포함시켜 반환하는 것으로 가능하게 할 수 있다.

➰ 예약 가능 시간을 확인한 후에는 그 시간대에 예약할 수 있는 링크를 삽입한다.

➰ 특정 시간에 예약을 완료하고 나서는 그 예약을 다시 확인할 수 있도록 링크를 작성해 넣는다.

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

 

📣  Open API

✔️ 정부에서 제공하는 공공데이터에 쉽게 접근할 수 있도록 정부는 Open API의 형태로 공공데이터를 제공한다.

➰ 글자 그대로 누구에게나 열려있는 API지만, API마다 정해진 이용 수칙이 있고 그에 따라 제한사항이 있을 수 있다.

➰ ex ) Open Weather Map 에서 제한적이나마 무료로 날씨 API를 사용할 수 있다. -> 데이터를 JSON 형태로 응답한다.

 

📣  API Key

✔️ API를 이용하기 위해서는 API Key가 필요하다.

➰ 서버의 문을 여는 열쇠로, 서버 운용에는 비용이 발생하기 때문에 서버 입장에서 누구나에게 아무런 조건 없이 데이터를 제공할 의무는 없다.

➰ API Key가 필요한 경우, 로그인한 이용자에게 자원에 접근할 수 있는 권한을 API Key의 형태로 제공하고, 데이터를 요청할 때 API Key를 같이 전달해야 원하는 응답을 받을 수 있다.