Unit8 회고

REST API

Rest API의 필요성🤓

웹 애플리케이션은 HTTP 메서드를 이용하여 서버와 통신을 하게되는데 이러한 메서드의 사용은 아무런 규칙 없이 이루어지는 것이 아니며 일종의 규약이 존재한다. 이것이 REST API를 통한 바람직한 요청과 응답 방법이 필요한 이유이다.

🔆 REST API 디자인

REST API❓

REST API는 웹에서 사용되는 데이터나 리소스를 HTTP URI로 표현하고 HTTP 를 통해 요청과 응답을 정의하는 방식을 말한다. 덧붙여 설명하자면 리소스는 URI를 통해 식별하고 어떠한 행위를 할 때에는 HTTP 메서드를 규정에 따라 사용하며 결과는 응답코드로 잘 작성하여 http의 원래 의미를 잘 활용하자는 것이 REST API의 핵심이라고 할 수 있다.

• Roy Fielding의 논문에서 웹(http)의 장점을 최대한 활용할 수 있는 아키텍처로 처음 소개됨
• 보기 쉽게 잘 작성된 메뉴판과 같은 역할을 API가 수행해야 하므로 적절한 REST API 디자인이 필요함

REST API 디자인 방법

• REST API를 작성할 때 지켜야 할 몇 가지 규칙이 있는데 Leonard Richardson이 REST API를 작 적용하기 위한 4단계 모델을 만듦
• Richardson의 성숙도 모델(RMM)
  • 0단계: HTTP 사용
  • 1단계: 개별 리소스와의 통신 준수
  • 2단계: HTTP 메서드 원칙 준수
  • 3단계: HATEOAS 원칙 준수
• Roy Fielding은 4가지 단계 모두 충족해야 REST API라고 주장하나 현실적으로 보았을 때 2단계까지만 충족시켜도 좋은 REST API 디자인이라고 볼 수 있음

🔆 REST API 성숙도 모델

1️⃣ 0단계

• REST API를 작성하기 위한 기본 단계
• 단순히 HTTP라는 통신 규약을 사용하는 단계
  • 0단계의 API는 REST API라고 보기 어려움

2️⃣ 1단계

• 개별 리소스와의 통신을 준수해야 하는 단계
  • 모든 자원은 개별 리소스에 맞는 endpoint를 사용해야하며 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 한다는 것이 REST API 1단계의 핵심
  • 즉, 요청하는 리소스가 무엇인지에 따라 각기 다른 endpoint로 구분 하여 사용

    endpoint란?🧐
    API가 기능을 수행하는 데 필요한 리소스에 접근할 수 위치로 API가 요청을 보내는 곳과 리소스가 있는 곳을 의미하며 endpoint에는 서버나 서비스의 URL이 포함될 수 있다❗️
    endpoint 관련 문서

  • 바람직한 endpoint 작성 방법
    • 🙁 동사, HTTP 메서드, 행위에 대한 단어 사용은 지양
    • 😁 리소스에 집중해 명사 형태의 단어로 작성
• 요청에 따른 응답으로 리소스를 전달할 때에는 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환할 것!

3️⃣ 2단계

• CRUD(Create, Read, Update, Delete)에 맞게 적절한 HTTP 메서드를 사용해야 하는 단계

  • 참고: HTTP 메서드의 종류

    요청	적절한 메소드
    조회(Read)	GET
    추가(Create)	POST
    갱신(Update)	PUT 또는 PATCH
    삭제(Delete)	DELETE

• ❗️HTTP 메서드 사용 시 유의해야 할 규칙❗️

  • GET 메서드는 서버의 데이터에 변화시키지 않는 요청에 사용
  • POST 메서드는 요청마다 새로운 리소스를 생성하며 PUT 메서드는 요청마다 같은 리소스를 반환
    • 멱등성을 가지는 PUT 메서드와 그렇지 않은 POST 메서드를 구분하여 사용할 것
  • PUT은 교체(전체 수정), PATCH는 수정(부분 수정)의 용도로 사용
    • PUT 메서드와 PATCH 메서드 역시 잘 구분하여 사용할 것

4️⃣ 3단계

• HATEOAS(Hypermedia As The Engine Of Application State)라는 약어로 표현되는 하이퍼미디어 컨트롤을 적용하는 단계
  • 요청은 2단계와 동일하나 응답에 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야 함
    • 응답에 들어가는 링크 요소는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함
    • 즉, 응답 내에 새로운 링크를 넣어 새로운 기능에 접근할 수 있도록 함

    hypermedia controls란?🤔
    리소스의 표현이 클라이언트에게 리소스가 무엇을 할 수 있는지 또는 수행할 수 있는 관련 작업을 알려야 한다는 개념을 의미한다.
    hypermedia controls

🔆 REST API 디자인 해보기

상황 예시: 숙박 시설 예약

• 박여행이라는 게스트가 김주인이라는 호스트에게 특정한 달에 예약 가능한 날짜를 확인해 예약하는 상황

1️⃣ RMM 0단계

• HTTP 프로토콜 사용

2️⃣ RMM 1단계

• 요청하는 리소스에 따라 endpoint 구분
  • 예약 가능한 날짜 확인의 응답으로 받는 리소스는 김주인 숙소의 예약 가능한 날짜
    • /host/김주인이라는 endpoint 사용
  • 특정 날짜 예약 후 slots의 1이라는 id를 가진 리소스가 변경
    • 특정 날짜를 예약하는 요청에서는 /slots/1이라는 endpoint 사용
• 리소스 정보와 함께 리소스 사용에 대한 성공/실패 여부도 반환

3️⃣ RMM 2단계

• CRUD에 맞는 적절한 HTTP 메서드 사용
  • 예약 가능한 날짜 확인 -> 조회(Read)
    • GET 메서드 사용
  • 특정 시간 예약 -> 생성(Create)
    • POST 메서드 사용
• 명확한 응답 코드 작성
  • 특정 시간 예약 후 201 Created라는 응답 코드로 새로운 예약이 생성되었음을 보여줌
• 관련 리소스 확인
  • 클라이언트가 Location 헤더에 작성된 URI를 통해 확인할 수 있도록 함

4️⃣ RMM 3단계

• 응답에 리소스의 URI를 포함한 링크 요소 삽입하여 작성
  • 링크 요소는 클라이언트가 응답을 받은 뒤 할 수 있는 다양한 액션을 위한 하이퍼미디어 컨트롤을 포함
    • 예약 날짜 확인 후 예약할 수 있는 링크 삽입
    • 예약 완료 후 예약을 확인하거나 취소할 수 있는 링크 삽입

🔆 Open API와 API Key

Open API

• 누구에게나 열려 있는 API
  • 누구에게나 열려 있지만 이것이 무제한으로 이용 가능하다는 말을 의미하는 것은 아니며 API마다 정해진 이용 수칙이나 이용 수칙에 따른 제한사항이 있을 수 있음

API Key

• 서버의 문을 여는 열쇠
  • API Key가 필요한 경우 로그인한 이용자에게 자원에 접근할 수 있는 권한을 API Key의 형태로 제공하며 이용자가 데이터 요청 시 API Key를 같이 전달해야 원하는 응답을 받을 수 있음

출처: code states
참고: 생활코딩

<오늘의 일기>
서버와 클라이언트가 통신하는 방식이 어렵게 느껴지면서도 이것을 통해 확장해 나갈 수 있는 것들을 그려보면 정말 유용하겠다는 생각이 들었던 이번 유닛. 사실 API의 개념이 굉장히 추상적이라는 생각이 들어 처음에는 그저 개념이 뇌 속에 들어왔다가 그대로 빠져나가는 것처럼 느껴졌는데(?) 여러 번 보다보니 개념적인 부분은 어느 정도 감이 잡혔지만 이것을 활용할 수있는 방법(예를 들어, open API로 날씨 데이터를 받아와 조작할 수 있는 방법)은 아직 잘 모르겠다. 앞으로 배워나가면서 여러 데이터를 내가 원하는대로 활용할 수 있을 정도의 수준으로 끌어올리는 연습을 많이 해야겠다.