(SEB_FE) Section2 Unit8 REST API

REST API에 대해 이해할 수 있다.
REST 성숙도 모델에 대해 이해할 수 있다.
REST API 문서를 읽을 수 있다.
REST API에 맞춰 디자인할 수 있다.
Open API와 API Key에 대해 이해할 수 있다.

🏀REST API

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

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

• 클라이언트와 서버 사이에도 데이터와 리소스를 요청하고, 요청에 따른 응답을 전달하기 위한 메뉴판이 필요한데, 만약 그 메뉴판이 알아보기 힘들게 되어있다면, 클라이언트는 좋은 주문을 할 수 없게된다.

즉, HTTP 프로토콜을 기반으로 요청과 응답에 따라 리소스를 주고받기 위해서 알아보기 쉽고 잘 작성된 메뉴판이 필요한데, 이 역할을 API가 수행해야 하므로 모두가 잘 알아볼 수 있도록 작성하는 것이 중요!!

🏅REST API를 디자인하는 방법

REST API를 작성할 때는 몇 가지 지켜야 할 규칙들이 있다.

로이 필딩은 이 모델의 모든 단계를 충족해야 REST API라고 부를 수 있다고 주장했지만, 실제로는 3단계까지 지켜지기 어렵기 때문에 2단계까지만 적용해도 좋은 API디자인이라고 볼 수 있다! (이런 경우를 HTTP API 라고도 부른다)

🏀리차드슨의 REST 성숙도 모델(4단계 모델)

🏅REST 성숙도 모델 - 0단계

0단계에서는 단순히 HTTP 프로토콜을 사용하기만 해도 된다.

물론 이 경우, 해당 API를 REST API라고 할 수는 없으며, 0단계는 REST API를 작성하기 위한 기본 단계인 것!

🏅REST 성숙도 모델 - 1단계

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

• 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야 한다

  • 어떤 리소스를 변화시키는지 혹은 어떤 응답이 제공되는지에 따라 각기 다른 엔드포인트를 사용하기 때문에, 적절한 엔드포인트를 작성하는 것이 중요하다.

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

• 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 한다

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

🏅REST 성숙도 모델 - 2단계

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

예를 들어,

• 예약 가능한 시간을 확인한다 ➡ 예약 가능한 시간을 조회(READ)한다

  • GET 메서드를 사용하여 요청을 보내기

  • 이때 GET 메서드는 body를 가지지 않기 때문에 query parameter를 사용하여 필요한 리소스를 전달

• 특정 시간에 예약한다 ➡ 해당 특정 시간에 예약을 생성(CREATE)한다

  • POST 메서드를 사용하여 요청을 보내야 한다.

  • POST 요청에 대한 응답이 어떻게 반환되는지 역시 중요
    (예를 들어, 새롭게 생성된 리소스를 응답으로 보낸다면, 코드를 201 Created로 명확히 작성하고 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인할 수 있도록 하기)

🚨HTTP 메서드를 사용할 때 몇가지 규칙에도 유의하기🚨

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

• POST 메서드는 요청마다 새로운 리소스를 생성하고 PUT 메서드는 요청마다 같은 리소스를 반환(멱등(idempotent)하다)
  ➡ 따라서, 멱등성을 가지는 메서드 PUT과 그렇지 않은 메서드 POST는 구분하여 사용해야 함

• PUT은 교체, PATCH는 수정의 용도! 이 둘도 잘 구분해서 사용해야 한다.

🏅REST 성숙도 모델 - 3단계

HATEOAS(Hypermedia As The Engine Of Application State)라는 약어로 표현되는 하이퍼미디어 컨트롤을 적용시키는 것

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

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

예를 들어, 예약 시스템에서
의사의 예약 가능 시간을 확인한 후 ➡ 그 시간대에 예약할 수 있는 링크를 삽입하거나,
특정 시간에 예약을 완료하고 나서 ➡ 그 예약을 다시 확인할 수 있는 링크를 삽입할 수 있다.

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

그리고 클라이언트 개발자는 이러한 응답에 담긴 링크들을 유용하게 사용할 수 있을지 눈여겨보아야 한다!

🏀Open API

누구에게나 열려있는 API.

그러나 "무제한으로 이용할 수 있다"라는 의미는 ❌❌❌!
➡ API마다 정해진 이용 수칙이 있고, 그 이용 수칙에 따라 제한사항(가격, 정보의 제한 등)이 있을 수 있으니 명심하자.

• 정부는 Open API의 형태로 공공데이터를 제공하고 있다.

• 공공데이터 포털에 접속해 원하는 키워드를 검색하면, 해당 키워드와 관련된 API를 확인할 수 있다!

🏅API Key

API를 이용하기 위해 이용하는 Key! 서버의 문을 여는 열쇠이다.

서버를 운용하는 데에 비용이 발생하기 때문에 서버 입장에서 아무런 조건 없이 익명의 클라이언트에게 데이터를 제공할 의무는 없다.

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