개요

API의 대표적인 아키텍처인 REST API를 알아봅니다.

---

학습 목표

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

---

REST API (Representational State Transfer)

정의

• 로이 필딩의 박사학위 논문에서 웹(http)의 장점을 최대한 활용할 수 있는 아키텍처로 처음 소개되었습니다.
• 웹에서 사용되는 데이터나 리소스를 HTTP URI 로 표현합니다.
• HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식입니다.
• 방법론

REST API 디자인

• HTTP 프로토콜 기반으로 요청과 응답에 따라 리소스를 주고받기 위해서 알아보기 쉽고 잘 작성된 메뉴판 이 필요한 것처럼 REST API 를 잘 디자인 해야합니다.
• 레오나르드 리차드슨이 REST API 를 잘 적용하기 위한 4단계 모델을 만들었습니다.
  • 0단계 : HTTP 사용
  • 1단계 : 개별 리소스와의 통신 준수
  • 2단계 : HTTP 메소드 원친 준수
  • 3단계 : HATEOAS 원칙 준수

• 로이 필딩은 이 모델의 모든 단계를 충족해야 REST API 라고 주장했습니다.
• 그러나 실제로 3단계까지 지키기 어렵기 때문에 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있습니다.
  • 2단계 까지 적용된 API 를 HTTP API 라고도 부릅니다.

REST 성숙도 모델 - 0단계

• HTTP 프로토콜을 사용하기만 해도됩니다.
• REST API 를 작성하기 위한 기본 단계입니다.
• 모든 요청에 POST 메서드 사용합니다.

• 엔드포인트로 모두 /appointment 사용하였습니다.

REST 성숙도 모델 - 1단계

• 개별 리소스와의 통신을 준수해야 합니다.
• 모든 자원은 개별 리소스에 맞는 엔드포인트를 사용해야합니다.
• 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 합니다.
• 모든 요청에 POST 메서드 사용합니다.

• 리소스에 따라 다른 엔드포인트 사용했습니다.
• 엔드포인트 작성 시에는 리소스 에 집중해 명사 형태의 단어로 작성하는 것이 바람직한 방법입니다.

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

REST 성숙도 모델 - 2단계

• CRUD 에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둡니다.
• 2단계까지 족용하면 대체적으로 잘 작성된 API 라고 합니다.
  • 대부분의 모범적인 API 디자인 조차 3단계 까지 적용한 경우는 드뭅니다.

• GET 메서드는 body 를 가지지 않기 때문에 query paramete 를 사용하여 필요한 리소스를 전달합니다.
• POST 요청에 대한 응답이 어떻게 반환되는지가 중요합니다.
  • 예시의 경우 응답은 새롭게 생성된 리소스를 보내주기 때문에 201 Created 로 명확한 응답 코드를 줘야합니다.
• 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI 를 통해 확인할 수 있도록 해야합니다.

• HTTP 메서드 사용시 규칙
  • GET : 서버의 데이터를 변화시키지 않는 요청에 사용 (READ only)
  • POST : 요청마다 새로운 리소스를 생성합니다. (Create)
  • PUT : 요청마다 같은 리소스를 반환하는 멱등성을 가빚니다. (Update - Change)
  • PATCH : 수정의 용도로 사용합니다. (Update - Update)

REST API 성숙도 모델 - 3단계

• 하이퍼미디어 컨트롤을 적용합니다.
• 응답에 리소스의 URI 를 포함한 링크 요소를 삽입하여 작성해야 합니다.
• 응답에 들어가게 되는 링크 요소는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있습니다.

• 위와 같이 허준이라는 의사의 예약 가능 시간을 확인한 후에 그 시간대에 예약 할 수 있는 링크 나 특정 시간에 예약을 완료하고 예약을 확인할 수 있는 링크 를 작성해 넣을 수 있습니다.
• 응답 내에 새로운 링크 를 넣어 새로운 기능에 접근 할 수 있도록 하는 것이 3단계의 핵심 포인트입니다.

Open API

• 누구에게나 열려있는 API 입니다.
• API 마다 정해진 이용 수칙이 있고 이용 수칙에 따라 제한 사항이 있을 수 있습니다.
  • 제한사항 : 가격 정보의 제한 등
• 공공데이터에 쉽게 접근할 수 있도록 정부에서 Open API 의 형태로 제공하고 있습니다.
• 대표적인 Open API - Open Weather Map
  • 제한적으로 무료 날씨 API 를 사용할 수 있습니다.
  • 데이터를 JSON 형태로 응답합니다.

API Key

• API 를 이용하기 위해서 API Key 가 필요합니다.
• 서버의 문을 여는 열쇠입니다.
• 로그인한 이용자에게 접근할 수 있는 권한을 API Key 의 형태로 제공하고 데이터를 요청할 때 API Key 를 같이 전달해야 원하는 응답을 받을 수 있습니다.

---

마치며

• 개인적으로 API 가 프론트엔드 개발자의 꽃이라고 생각하기 때문에 재미있었습니다.
• 얼른 직접 API 를 구현하고 싶어졌습니다.
• 최근에는 GraphQL 을 활용한 API 구현도 트렌드로 알고 있는데 공부해봐야 겠습니다.

---

참조

코드스테이츠 프론트엔드 부트캠프