1. REST API

• REST API
  웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식
• REST API를 디자인하는 방법
  • 리차드슨의 REST 성숙도 모델
    : 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있고, 이런 경우를 HTTP API 라고도 부른다.
    

1-1. REST 성숙도 모델 - 0단계

• 0단계는 REST API를 작성하기 위한 기본 단계
• 모든 요청에서 엔드포인트로 /appointment를 사용
• 예시
  

1-2. REST 성숙도 모델 - 1단계

• 1단계에서는 개별 리소스(Resource)와의 통신을 준수해야 한다.
• 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야하며
  요청하고 받는 자원에 대한 정보를 응답으로 전달해야 한다는 것이 1단계의 핵심
• 엔드포인트 작성방법
  • 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직하다.
  • 동사, HTTP 메소드, 혹은 어떤 행위에 대한 단어 사용은 지양한다.
• 더불어 요청에 따른 응답으로 리소스를 전달할 때에도 사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환해야 한다.
• 예시
  ex 1) 예약 가능한 시간 확인 요청 -> "엔드포인트" : /doctors/허준
  → 응답: 데이터(리소스) -> 의사 허준의 예약 가능한 시간대
  ex 2) 특정 시간에 예약 요청 -> "엔드포인트" : /slots/123 실제 변경되는 리소스 요청
  -> 예약이 불가능할 경우 ? 응답 : 리소스 사용에 대한 실패 여부를 포함한 응답을 받는다.
  

1-3. REST 성숙도 모델 - 2단계

• REST 성숙도 모델 2단계에서는 CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둔다.
• HTTP 메서드를 사용할 때 몇가지 규칙
  • GET 메서드 같은 경우는 서버의 데이터를 변화시키지 않는 요청에 사용해야 한다.
  • POST 메서드는 요청마다 새로운 리소스를 생성하고 PUT 메서드는 요청마다 같은 리소스를 반환한다.
    이렇게 매 요청마다 같은 리소스를 반환하는 특징을 멱등()하다고 한다.그렇기 때문에 멱등성을 가지는 메서드 PUT과 그렇지 않은 메서드POST는 구분하여 사용해야 한다.
  • PUT 메서드와 PATCH 메서드도 구분하여 사용해야 한다. PUT은 교체, PATCH는 수정의 용도로 사용한다.
• 예시
  ex 1) 예약 가능한 시간을 조회(READ)하기 위해 GET 로 요청
  → GET 메소드는 body를 가지지 않기 때문에 query parameter를 사용하여 리소스 전달
  -> 응답: 데이터(리소스) -> 의사 허준의 예약 가능한 시간대
  ex 2) 특정 시간에 예약을 생성(CREATE)하기 위해 POST 로 요청
  → 응답 : 새롭게 생성된 리소스 → 상태코드 201 Created 로 명확하게!

1-4. REST 성숙도 모델 - 3단계

• 마지막 단계는 HATEOAS(Hypermedia As The Engine Of Application State)라는 약어로 표현되는 하이퍼미디어 컨트롤을 적용한다.
• 3단계의 요청은 2단계와 동일하지만, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야 한다.
• 예시
  ex) 예약 가능 시간을 확인 요청-> 응답 : 예약을 할 수 있는 링크를 삽입하여 응답
  

1-5. Open API와 API Key

• Open API

  • 공공데이터에 쉽게 접근할 수 있도록 정부는 Open API의 형태로 공공데이터를 제공하고 있다.
  • 공공데이터 포털에 접속해 원하는 키워드를 검색하면, 해당 키워드와 관련된 API를 확인할 수 있다.
  • 'open'이라는 키워드가 붙어있지만, 무제한으로 이용할수 있는것은 아니다.
    API마다 정해진 이용 수칙이 있고, 그 이용 수칙에 따라 제한사항(가격, 정보의 제한 등)이 있을 수 있다.

• API Key

  • API를 이용하기 위해서는 API Key가 필요하다. (가끔 API key가 필요하지 않은 경우도 있다.)
  • API Key가 필요한 경우에는 로그인한 이용자에게 자원에 접근할 수 있는 권한을 API Key의 형태로 제공하고, 데이터를 요청할 때 API key를 같이 전달해야 원하는 응답을 받을 수 있다.