💡 Rest (Representational State Transfer) API
웹에서 사용되는 데이터나 자원을 HTTP URI로 표현하고, HTTP프로토콜을 통해 요청과 응답을 정의하는 방식
잘 만들어진 메뉴판을 의미한다.
음식점의 메뉴판이 있다고 해도, 가독성이 떨어지고 이해하기 어렵게 되어있다면, 있으나마나 일 것이다.
API도 마찬가지로 난잡하게 되어있다면, 이해하기도 어렵고 활용하기에도 쉽지 않을 것이다.
즉, Rest API는 클라이언트와 서버 간의 통신을 위한 잘 만들어진 메뉴판을 작성하는 방식을 의미한다.
💡 Richardson의 REST 성숙도 모델
REST 방법론을 보다 실용적으로 적용하기 위한 모델
총 4단계 (0~3단계)로 나뉘어진다.
REST API를 처음 소개한 로이필딩은 이 모든 단계를 충족해야 Rest API라고 부를 수 있다고 주장했다.
(하지만, 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있고, 이런 경우를 HTTP API라고 부른다.)
🔍 0단계
HTTP 프로토콜 사용
(출처 : 코드스테이츠)
위의 예시처럼, 예약 가능한 시간을 확인하고, 특정 시간에 예약하는 상황에서 HTTP프로토콜을 사용하고 있다.
이처럼, HTTP프로토콜을 사용했다면 일단 0단계는 충족을 한 것이다.
🔍 1단계
개별 리소스와 통신 준수
REST API는 웹에서 사용되는 모든 데이터나 자원을 HTTP URI로 표현한다.
그렇기때문에, 모든 자원은 개별 리소스에 맞는 EndPoint를 사용해야하며,
요청하고 받는 자원에 대한 정보를 응답으로 전달해야한다.
0단계에서는 endpoint가 /appointment 였다.
하지만, 1단계에서는 요청하는 리소스가 무엇인지에 따라 각기 다른 endpoint를 사용한다.
위의 예시를 보면, 예약 가능한 시간을 확인하기 위해서는 의사의 스케쥴이 필요하기 때문에 '/doctors/허준' 을 endpoint로 사용하였다.
마친가지로 특정 시간에 예약을 하기 위해서 slot의 선택한 예약시간대를 endpoint로 사용한 것을 볼 수 있다.
즉, 이처럼 요청하는 리소스에 따라 endpoint를 달리 지정하는 것이 1단계의 핵심이다.
🔍 2단계
HTTP 메소드 원칙 준수
앞서 본 0, 1단계에서는 모든 요청을 POST 메소드로 하고 있다.
2단계는 각 메소드를 CRUD에 맞춰서 사용하는 것이 핵심이다.
위의 사례로 생각해본다면, 예약 가능한 시간을 확인한다는 것은 '조회'에 해당한다.
즉, 조회는 CRUD 중 Read에 해당하기 때문에 GET 메소드를 사용해야 한다.
그리고, 특정 시간에 예약한다는 것은 새로운 예약을 생성하는 것이 때문에, CRUD 중 CREATE에 해당한다.
그렇기 때문에, POST 메소드를 사용해야 한다.
POST메소드는 새롭게 생성된 리소스를 보내주기 때문에, 응답코드를 201 Created로 작성해주고(명확하게 써 줘야 한다), Location의 URI를 Client가 보고 확인할 수 있으면, 2단계가 충족된 것이다.
📌 HTTP 메소드 사용 규칙
-
GET메소드는 서버의 데이터를 변화시키지 않는 요청에 사용해야 한다.
-
멱등성을 가지지 않는 POST메소드와 멱등성을 갖는 PUT메소드를 구분해서 사용해야한다.
(멱등성 : 매 요청마다 같은 리소스를 반환하는 특징)
-
교체의 용도의 PUT과 수정의 용도인 PATCH를 구분해서 사용해야 한다.
🔍 3단계
HATEOAS 원칙 준수
📌 HATEOAS (Hypertext As The Engine Of Application State)
요청에 필요한 URI를 응답에 포함시켜 반환함으로써 클라이언트가 전적으로 서버와 동적인 상호작용이 가능하도록 하는 것
3단계의 요청은 2단계와 동일하지만, 응답에는 links를 넣어 새로운 기능에 접근할 수 있도록 해준다.
여기서 말하는 새로운 기능이란,
예약가능한 시간대를 확인하는 GET요청을 보냈다면, 그 시간대에 예약할 수 있는 링크나,
예약을 완료한 후라면, 그 예약을 다시 확인할 수 있는 링크를 말한다.
💡 Open API
개발자라면 누구나 사용할 수 있도록 공개된 API
대표적으로 공공데이터포털 사이트에서 Open API를 확인할 수 있는데, 위의 사진처럼 HTTP 메세지에 대한 정보가 나와있다.
우리는 저 Request URL을 통해 JSON파일 형태의 정보를 받아올 수 있다.
📌 API key
서버의 문을 여는 열쇠
API를 이용하기 위해서는 API Key가 필요한데
이때, 서버를 운용하는데 비용이 발생하기 때문에 아무 조건없이 클라이언트에게 데이터를 무상으로 제공할 의무는 없다. (API key가 필요없는 경우도 있다.)
headers: {
'X-RapidAPI-Key': '...' ,
'X-RapidAPI-Host': '...'
}그래서 위와 같이, 로그인한 유저에 대해서 자원에 접근할 수 있는 권한을 API key 형태로 제공한다.
이러한 API는 반드시 API key를 같이 전달해야 원하는 응답을 받을 수 있다.
