[Week 5-2] HTTP/네트워크 실습

Achivement Goals

• REST API에 대해 이해할 수 있다.
  • REST API 문서를 읽을 수 있다.
  • REST API에 맞춰 디자인할 수 있다.
  • Open API와 API Key에 대해 이해할 수 있다.
• Postman이 무엇인지 이해하고 사용할 수 있다.
  • HTTP API 테스팅이 무엇인지 알 수 있다.
  • Postman을 사용하여 서버에 GET, POST 요청을 보내고 응답을 받을 수 있다.
  • (Optional) Postman을 사용하여 Open Weather Map Open API에 요청을 보낼 수 있다.
• Chrome Network Tab을 이해할 수 있다.
  • Chrome Network Tab 사용 방법을 익히고 사용할 수 있다.

 

REST API란?

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

식당에서 가독성이 떨어지는 메뉴판 사용하는 것을 지양하듯이 웹에서는 API 수행으로 잘 알아볼 수 있게 해야한다.

REST 성숙도 모델 - 0단계

REST 성숙도 모델에 따르면, 0단계에서는 단순히 HTTP 프로토콜을 사용하기만 해도 된다. 물론 이 경우, 해당 API를 REST API라고 할 수는 없으며, 0단계는 좋은 REST API를 작성하기 위한 기본 단계이다.

0단계

REST 성숙도 모델 - 1단계

REST 성숙도 모델에 따르면, 1단계에서는 개별 리소스와의 통신을 준수해야 한다고 한다.

 

조금 더 쉽게 말하면, 앞서 REST API는 웹에서 사용되는 모든 데이터나 자원(Resource)을 HTTP URI로 표현한다고 이야기했다.

그래서 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야 한다는 것과 요청하고 받은 자원에 대한 정보를 응답으로 전달해야 한다는 것이 1단계에서 의미하는 바 이다.

앞서 0단계에서는 모든 요청에서 엔드포인트로 /appointment를 사용하였다. 하지만 1단계에서는 요청하는 리소스가 무엇인지에 따라 각기 다른 엔드포인트로 구분하여 사용해야 한다.

1단계

REST 성숙도 모델 - 2단계

REST 성숙도 모델 2단계에서는 CRUD에 맞게 적절한 HTTP 메소드를 사용하는 것에 중점을 둔다. 앞서 0단계와 1단계 예시에서 보았듯, 모든 요청을 CRUD에 상관없이 POST로 하고 있다. 그러나 REST 성숙도 모델 2단계에 따르면 이는 CRUD에 따른 적합한 메소드를 사용한 것은 아니다.

응답은 새롭게 생성된 리소스를 보내주기 때문에, 응답 코드도 201 Created 로 명확하게 작성해야 하며, 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인 할 수 있도록 해야, 완벽하게 REST 성숙도 모델의 2단계를 충족한 것이라고 볼 수 있다.

2단계

메소드를 사용할 때도 규칙이 있다.

• GET 메소드 같은 경우는 서버의 데이터를 변화시키지 않는 요청에 사용해야 합니다.
• POST 는 요청마다 새로운 리소스를 생성하고 PUT 은 요청마다 같은 리소스를 반환합니다. 이렇게 매 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 합니다. 그렇기 때문에 멱등성을 가지는 메소드 PUT과 그렇지 않은 POST는 구분하여 사용해야 합니다.
• PUT 과 PATCH 도 구분하여 사용해야 합니다. PUT은 교체, PATCH는 수정의 용도로 사용합니다.
• 더 자세한 내용을 학습하고 싶다면 MDN HTTP request methods 를 읽어보기 바랍니다.

REST 성숙도 모델 - 3단계

마지막 단계는 HATEOAS(Hypertext As The Engine Of Application State)라는 약어로 표현되는 하이퍼미디어 컨트롤을 적용한다. 3단계의 요청은 2단계와 동일하지만, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성한다는 것이 다르다.

3단계

Reference

위의 원칙에 따라 API를 작성했다면 가장 좋겠지만, 개발자 혹은 개발 상황에 따라 위의 원칙을 꼭 지키지 못할 수도 있다. 다음의 다양한 API를 참고하여, 모범적인 API 디자인을 할 수 있도록 학습해보자.

• 5가지의 기본적인 REST API 디자인 가이드
• 구글 API 작성 가이드
• MS의 REST API 가이드라인

 

Open API

정부에서 제공하는 공공데이터가 있다. 공공데이터에 쉽게 접근할 수 있도록 정부는 Open API의 형태로 공공데이터를 제공하고 있다. 공공데이터포털에 접속해 원하는 키워드를 검색하면, 해당 키워드와 관련된 API를 확인할 수 있다.

이 API에는 "Open"이라는 키워드가 붙어 있다. 글자 그대로 누구에게나 열려있는 API다. 그러나 "무제한으로 이용할 수 있다"는 의미는 아니다. 기관이나 API마다 정해진 이용 수칙이 있고, 그 이용 수칙에 따라 제한사항(가격, 정보의 제한 등)이 있을 수 있다.

Open API를 간단하게 경험해 볼 수 있는 대표적인 페이지는, Open Weather Map이라는 웹 사이트에서 제공하는 날씨 API다. 이 웹사이트에서는 다음의 설명처럼 데이터를 제공한다.

• 제한적이나마 무료로 날씨 API를 사용할 수 있습니다.
  • 프리 플랜에서는 기본적으로 분당 60번, 달마다 1백 번 호출이 가능합니다.
• 데이터를 JSON 형태로 응답합니다.

API Key

API를 이용하기 위해서는 API Key가 필요하다. API key는 서버의 문을 여는 열쇠라고 생각할 수 있다. 클라이언트의 요청에 따라 서버에서 응답한다는 말은 결국 서버를 운용하는 데에 비용이 발생한다는 말이다. 따라서 서버 입장에서 아무런 조건 없이 익명의 클라이언트에게 데이터를 제공할 의무도, 이유도 없다. (가끔 API key가 필요하지 않은 경우도 있다.)

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

 

HTTP API 테스트 도구

HTTP 요청을 테스트할 수 있는 다양한 도구가 있다. 많은 API가 HTTP 프로토콜을 이용하므로, API 테스트 도구라고 부른다. 이러한 API 테스트 도구는 클라이언트 입장에서 서버 API를 테스트하거나, API를 만드는 과정에서도 매우 유용하다.

HTTP API 테스트 도구 (CLI)

• curl (대부분의 리눅스 환경에 내장되어 있습니다.)
• wuzz

HTTP API 테스트 도구 (GUI)

• Postman
• Insomnia

Chrome Network Tab 사용 방법

 

Postman 관련