REST API

◎ REST API

• API(Application Programming Interface)

  • 응용 프로그램에서 사용할 수 있도록, 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스
  • 데이터를 주고 받기 위한 방법과 그 규격 (API의 문서가 필요)

• REST API(Representational State Transfer API)

  • REST 아키텍처의 제약 조건을 준수하는 애플리케이션 프로그래밍 인터페이스 추가 자료1 추가 자료2

  • REST

    • HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고,
    • HTTP Method(POST, GET, PUT, DELETE)를 통해
    • 해당 자원(URI)에 대한 CRUD Operation을 적용하는 것을 의미합니다.

  • 추가적인 정의

    • 웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식
    • 웹(http)의 장점을 최대한 활용할 수 있는 아키텍처 (로이 필딩의 박사학위 논문)

◎ 좋은 REST API를 디자인하는 방법

• REST 성숙도 모델 - 0단계

  • 단순히 HTTP 프로토콜을 사용
  • 해당 API를 REST API라고 할 수는 없으며, 0단계는 좋은 REST API를 작성하기 위한 기본 단계
  • 

• REST 성숙도 모델 - 1단계

  • 개별 리소스와의 통신을 준수
    • 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용
    • 요청하고 받은 자원에 대한 정보를 응답으로 전달해야 한다
  • 예시 보기
    • "허준"의 비어있는 예약시간만 보고 싶으므로 엔드 포인트를 /doctors/허준 으로 함
    • 특정 slot에 예약을 하고 싶으므로 엔드 포인트를 /slots/123 으로 함
    • 응답으로 리소스를 전달할 때에도 사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환
  • 

• REST 성숙도 모델 - 2단계

  • CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점
  • 메서드 사용 규칙
    • GET : 서버의 데이터를 변화시키지 않는 요청
    • POST : 요청마다 새로운 리소스를 생성 (멱등성 X)
    • PUT : 요청마다 같은 리소스를 반환 (멱등성 O)
    • PATCH : 수정의 용도 (PUT은 교체의 용도)
    • DELETE : 특정 부분 제거, 초기화
  • REST 성숙도 모델의 2단계까지 적용을 하면 대체적으로 잘 작성된 API라고 여김
  • 예시보기
    • 조회시 메서드를 GET을 사용, GET은 바디를 쓸 수 없으므로 query를 사용하여 정보를 줌
  • 

• REST 성숙도 모델 - 3단계

  • 하이퍼미디어 컨트롤을 적용 : HATEOAS(Hypertext As The Engine Of Application State)
    • 요청은 2단계와 동일하지만, 응답에 리소스의 URI를 포함한 링크 요소를 삽입하여 작성
  • 예시보기
    • 조회시에 예약할 수 있는 링크를 삽입
    • 예약시에 조회, 취소할수 있는 링크를 삽입
  • 

• 참고 자료

  • 기본적인 REST API 디자인 가이드
  • MS REST API Guidelines
  • REST란?