D-31

🔍 REST API

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

HTTP 프로토콜을 기반으로 요청과 응답에 따라 리소스를 주고받기 위해서 알아보기 쉽고 잘 작성된 메뉴판이 필요하다. 이 역할을 API가 수행해야 하기 때문에 잘 알아볼 수 있도록 작성해야한다.

🔍 URL (endpoint)

URL은 요청할 데이터의 위치를 가리킨다.
URL은 root-endpoint와 path로 나뉘는데
root-endpoint는 서버의 기본 주소이고 path는 세부 경로다.

예를 들어 https://api.example.com/users라는 URL이 있다면
https://api.example.com은 root-endpoint이고 /users는 path다.
root-endpoint는 요청할 서버를, path는 데이터가 위치한 세부 경로를 가리킨다.

때로는 옵션을 주기 위해 URL에 query parameter를 포함시키기도 한다.
하나의 query parameter는 key와 value를 쌍으로 이루고 제일 앞에 ?를 붙인다.
여러 parameter를 넣을 수 있고 각 parameter는 &로 구분한다.

https://api.example.com/users?query1=value1&query2=value2

---

🔍 REST 성숙도 모델 4단계

위 4단계 중 2단계까지만 적용해도 좋은 API 디자인이라 볼 수 있다.
이 경우를 HTTP API라 부른다.

📌 REST 성숙도 모델 - 0단계

REST API를 작성하기 위한 기본 단계다.

해당 API는 REST API라 할 수 없다.

모든 요청에서 엔드포인트로 /appointment 를 사용한다.

📌 REST 성숙도 모델 - 1단계

개별 리소스(Resource)와의 통신을 준수해야한다.

개별 리소스에 맞는 엔드포인트를 사용해야 하는 것과 요청하고 받은 자원에 대한 정보를 응답으로 전달해야한다. 이 때 응답으로 리소스를 전달할 경우에도 사용한 리소스에 대한 정보와 같이 리소스 사용에 대한 성공/실패 여부를 반환해야한다.

엔드포인트 (Endpoint) 작성방법

리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직하다.

동사, HTTP 메소드, 혹은 어떤 행위에 대한 단어 사용은 지양한다.

📌 REST 성숙도 모델 - 2단계

CRUD에 맞는 적절한 HTTP 메서드를 사용해야 한다.

자원에 대한 행위는 HTTP Method인 GET, POST, PUT, DELETE 등으로 표현한다.

💡 HTTP METHOD 4가지

METHOD	역할
POST	POST를 통해 해당 URI를 요청하면 리소스를 생성한다.
GET	GET을 통해 해당 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져온다.
PUT	PUT을 통해 해당 리소스를 수정한다.
DELETE	DELETE를 통해 리소스를 삭제한다.

📌 REST 성숙도 모델 - 2단계

3단계는 2단계와 동일하지만, 응답에 리소스의 URI를 포함한 링크가 포함되어야 한다.

HATEOAS(Hypertext As The Engine Of Application State) 원칙을 준수한다.

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

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

---

🔍 Open API와 API KEY

Open API

Open API는 누구에게나 열려있는 API를 뜻한다. 하지만 완전 무료라는 의미는 아니다. 각 API마다 정해진 이용 수칙이 있고 이에 따라 가격이나 제한사항 등이 있을 수 있다. Open API로는 정부에서 제공하는 공공 데이터, 기업체에서 개발한 API 등이 있다.

API Key

API Key는 서버의 문을 여는 열쇠라 할 수 있다. API를 이용하기 위해 이 API Key가 필요한데, 클라이언트의 요청에 따라 서버에서 응답한다는 것은 서버를 운용하는데 비용이 발생한다는 뜻이다. 따라서 서버는 아무 조건 없이 클라이언트에게 데이터를 제공할 의무가 없기 때문에 이 API Key를 사용한다. 하지만 모든 API에 API Key가 있지 않다.

API Key는 특정 사용자에게만 리소스에 접근할 수 있는 권한을 제공하고,
데이터를 요청할 때 API Key를 같이 전달해 원하는 응답을 받을 수 있게 하는 것이다.