Chapter 1. REST API

학습 목표

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

1-1. REST API 디자인

---

REST API

• REST : Representational State Transfer
• 웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식
• API의 역할
  • HTTP 프로토콜 기반으로 요청과 응답에 따라 리소스를 주고받기 위해서, 알아보기 쉽고 잘 작성된 메뉴판 같은 역할(⭐️)

💡) REST API 더 알아보기
REST API는 클라이언트와 서버 간의 통신과 데이터 교환을 가능하게 한다.

• REST API의 주요 특징
  • 자원(Resources)
    • REST에서는 모든 것을 자원으로 간주한다.
    • 자원은 객체의 집합이나 단일 객체를 의미하고, 고유한 URI를 사용하여 식별된다.
    • 자원은 해당하는 엔드 포인트를 통해 접근할 수 있다.
  • HTTP 메서드
    • RESTful API는 자원에 대한 작업을 수행하기 위해 HTTP 메서드를 사용한다.
    • 가장 일반적으로 사용되는 메서드
      • GET : 자원이나 자원의 컬렉션을 가져온다.
      • POST : 새로운 자원을 생성한다.
      • PUT : 기존 자원을 업데이트한다.
      • DELETE : 자원을 삭제한다.
  • 무상태(Stateless)
    • RESTful API는 상태를 유지하지 않는 특징을 가진다.
    • 각 요청이 독립적으로 처리되어야 하고, 요청에 필요한 모든 정보는 요청 자체에 포함되어야 한다.
    • 서버는 세션 상태를 관리하지 않는다.
  • 표현(Representation)
    • REST API는 자원의 표현을 사용하여 데이터를 전달한다.
    • 표현은 주로 JSON, XML, 또는 HTML과 같은 형식으로 이루어진다.
    • 클라이언트는 요청을 보낼 때 표현 형식을 지정할 수 있으며, 서버는 해당 형식으로 응답을 제공한다.
  • 인터페이스 일관성
    • RESTful API는 일관된 인터페이스를 유지하는 것이 중요하다.
    • 자원에 대한 작업을 위한 공통된 기본 원칙과 규칙을 의미한다.
    • 예를 들어, URI는 자원을 식별하고, HTTP 메서드는 자원에 대한 동작을 정의하는데 사용된다.

REST API를 디자인

• REST API를 작성할 때는 몇 가지 규칙이 있음
• 4단계 모델로, 성숙도 모델이라고 함

• 성숙도 모델은 총 4단계로 나누어지며, 이 모델의 모든 단계를 충족해야 REST API라고 부를 수 있다고 하는 주장도 있지만(로이 필딩)
• 3단계까지 지키기가 어렵기 때문에 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있음(HTTP API 라고 부름)

💡) 왜 3단계까지 지키기가 어려울까요?
1. 기술적인 복잡성
높은 성숙도 단계에 도달하려면 기술적으로 복잡한 문제를 해결해야한다. 복잡한 아키텍처, 확장성 문제, 데이터 일관성 등과 같은 기술적인 도전 과제가 발생할 수 있다.

2. 조직 문화와 프로세스
성숙도 모델의 다음 단계로 진행하기 위해서는 조직 내에서 변화를 수용하고, 새로운 프로세스롸 문화를 적용해야 할 수도 있다. 이런 점은 조직의 역량, 리소스 및 문화 변화에 대한 도전과제가 될 수 있다.

3. 리소스 제한
높은 성숙도 단계로 진행하려면 충분한 리소스(인력, 예산, 기술 등)가 필요한데, 이러한 리소스 제한은 다음 단계로 진행하는 것을 어렵게 만들 수 있다.

4. 외부 의존성
조직의 성숙도 단계에 따라 외부 시스템, 파트너, 인프라 등과의 의존성이 증가할 수 있다. 외부 요소에 대한 제어 불가능성이 진행을 어렵게 만들 수 있다.

이 밖에도 다양한 이유들이 있겠지만, 추가적인 노력과 리소스가 필요할 수 있으며, 조직이 이러한 도전과제를 인식하고, 적절한 전략과 계획을 수립하여야 다음 단계로의 진행을 꾀할 수 있다.

1-2~1-5. REST 성숙도 모델

---

0단계

• 0단계는 REST API를 작성하기 위한 기본 단계
• 단순히 HTTP 프로토콜을 사용하기만 해도 됨(but, API라고 할 수 없음)

1단계

• 개별 리소스(Resource)와의 통신을 준수해야 함
• REST API는 웹에서 사용되는 모든 데이터나 자원(Resource)을 HTTP URI로 표현하는데, 이에 따라, 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야 함
  • 리소스에 집중하여 명사 형태의 단어로 작성
• 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 함

• 0단계에서는 요청에서의 엔드포인트가 모두 동일할 수 있지만, 1단계에서는 요청하는 리소스가 무엇인지에 따라 각기 다른 엔드포인트로 구분하여 사용

2단계

• CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둠
• HTTP 메서드를 사용할 때 몇 가지 규칙에도 유의해야 함
  • GET 메서드 같은 경우는 서버의 데이터를 변화시키지 않는 요청에 사용해야 한다.
  • POST 메서드는 요청마다 새로운 리소스를 생성하고 PUT 메서드는 요청마다 같은 리소스를 반환한다. 이렇게 매 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 한다. 그렇기 때문에 멱등성을 가지는 메서드 PUT과 그렇지 않은 메서드 POST는 구분하여 사용해야 한다.
  • PUT 메서드와 PATCH 메서드도 구분하여 사용해야 합니다. PUT은 교체, PATCH는 수정의 용도로 사용합니다.

3단계

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

1-6. Open API와 API Key

---

Open API

• 정부에서 제공하는 공공데이터에 쉽게 접근할 수 있도록 하는 것
  • 정부에서 Open API의 형태로 데공
• 공공데이터 포털에 접속해 원하는 키워드를 검색하면 해당 키워드와 관련된 API를 확인할 수 있음
• 말그대로 누구에게나 열려 있는 API이지만, API마다 정해진 이용 수칙이 있고, 그 이용 수칙에 따라 제한사항이 있을 수 있음

API Key

• API를 이용하기 위해서 필요한 것
  • 서버의 문을 여는 열쇠
• 아무런 조건 없이 데이커를 제공할 의무는 없기 때문에, 로그인한 이용자에게 자원에 접근할 수 있는 권한을 API Key의 형태로 제공하고, 데이터를 요청할 때 API Key를 같이 전달해야 원하는 응답을 받을 수 있음

---

❓) 궁금증

• REST API, RESTful API의 차이?
• PUT 과 PATCH는 무엇이 다른가?
• 엔드포인트?