REST API

REST API

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

❓

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

 

REST API를 디자인하는 방법

• 레오나르드 리차드슨(Leonard Richardson)은 REST API를 잘 적용하기 위한 4단계 모델을 만듦
  • 로이 필딩은 위 모델의 모든 단계를 총족해야 REST API라고 부를 수 있다고 주장
  • 실제론 3단계까지 지키지 어렵기 때문에 2단계까지 적용해도 좋은 API 디자인이라고 볼 수 있음 (= HTTP API)

<REST 성숙도 모델 - 0단계>

• 0단계에서는 단순히 HTTP 프로토콜을 사용하기만 해도 됨(해당 API를 REST API라고 할 수 없으며, REST API를 작성하기 위한 기본 단계)
  • 위 예시와 같이 단순히 HTTP 프로토콜을 사용하는 것이 REST API의 출발점
  • 0단계에서는 요청에서의 엔드포인트로 모두 /appointment 를 사용

<REST 성숙도 모델 - 1단계>

• 1단계에서는 개별 리소스(Resource)와의 통신을 준수

• 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야하며, 요청하고 받는 자원에 대한 정보를 응답으로 전달한다는 것이 1단계 핵심
  • 위의 예시
    • 요청 : 예약 가능한 시간 확인 (요청 시 /doctors/허준 이라는 엔드포인트를 사용)
    • 응답 : 허준이라는 의사의 예약가능한 시간대를 자원(리소스)
    • 요청 : 특정 시간 예약 (요청 시 slots라는 리소스의 123이라는 id를 가진 리소스가 변경되기 때문에, 하단의 특정 시간에 예약이라는 요청에서는 /slots/123 으로 실제 변경되는 리소스를 엔드포인트로 사용)

    ❗

    예시와 같이 어떤 리소스를 변화시키는지 혹은 어떤 응답을 제공되는지에 따라 각기 다른 엔드포인트 사용 > 적절한 엔드포인트를 작성하는 것이 중요
    <엔드포인트 작성 시>
    1. 동사, HTTP 메서드,어떤 행위에 대한 단어 사용 지양
    2. 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직함

  
  • 응답 : 리소스를 전달할 때에도 사용한 리소스에 대한 정보와 함께 사용에 대한 성공/실패 여부를 반환

<REST 성숙도 모델 - 2단계>

• 2단계에서는 CRUD(Create, Read, Update, Delete)에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둠
  • 조회(Read) : 예약 가능 시간을 확인
    • GET 메서드를 사용하여 요청 (GET 메서드는 body 를 가지지 않기 때문에 query parameter를 사용하여 필요한 리소스를 전달)
  • 생성(Create) : 특정 시간에 예약
    • POST 메서드를 사용하여 요청, POST 요청에 대한 응답이 어떻게 반환되는지가 중요
    • 응답 코드는 201 Created 로 명확하게 작성 (관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인할 수 있도록 하면 완벽하게 REST 성숙도 모델의 2단계를 충족)

• HTTP 메서드 를 사용할 때 규칙
  • GET : 서버의 데이터를 변화시키지 않는 요청에 사용
  • POST : 요청마다 새로운 리소스를 생성, PUT : 요청마다 같은 리소스 반환
    • 멱등(idempotent)하다 : 매 요청마다 같은 리소스를 반환하는 특징 (멱득성을 가지는 메서드 PUT 과 그렇지 않은 메서드 POST 는 구분하여 사용
  • PUT : 교체, PATCH : 수정

<REST 성숙도 모델 - 3단계>

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

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

• 응답 내에 새로운 링크를 넣어 새로운 기능에 접근할 수 있도록 하는 것이 3단계의 핵심 포인트 (클라이언트 개발자들이 응답에 담겨 있는 링크들을 눈여겨본다면, 이러한 링크들은 조금 더 쉽고, 효율적으로 리소스와 기능에 접근할 수 있게 하는 요소가 될 수 있음)
  • 아래 예시와 같이 허준이라는 예약 가능 시간을 확인한 후, 그 시간대에 예약할 수 있는 링크를 삽입하거나, 특정 시간에 예약을 완료하고 나서 그 예약을 다시 확인할 수 있도록 링크를 작성
  

레퍼런스

구글, 마이크로소프트 같은 대기업도 REST API에 대한 가이드라인을 제시하고 있습니다. REST API의 모범적인 사례는 공신력 있는 가이드라인을 참고하세요.

• 구글 REST API 작성 가이드라인

• 마이크로소프트 REST API 작성 가이드라인

 

[사진 출처] : 코드스테이츠