[network] REST/REST API

개요

• REST(Representational State Transfer)
• 로이 필딩(Roy Fielding)의 2000년 박사학위 논문에서 소개
• 네트워크 통신 설계 지침
  • 리소스를 정의하고 리소스에 대한 주소를 지정하기 위한 방법
  • 프로토콜이 아닌 일련의 아키텍처 제약
• 네트워크 통신을 위한 지침이지만 네트워크의 대부분이 WWW(World Wide Web)이므로 웹 통신에 주로 사용

REST API, RESTful API

• REST 제약 조건를 준수하는 HTTP API
• 제약 조건을 지키지 않았지만 REST API라고 부르는 경우도 적지 않음

HTTP API

• 현제 대부분의 HTTP API는 RESTful을 지향하므로 REST API와 같은 의미로 쓰임

제약 조건

• client-server	클라이언트와 서버로 분리되어야 하며 의존성이 없어야 한다.
  stateless	상태 정보를 저장하지 않는다. 즉 요청자, 요청 위치와 상관 없이 결과가 동일해야 한다.
  cache	네트워크 프로토콜에서 제공하는 캐싱 기능을 적용할 수 있어야 한다.
  uniform Interface	표준 형식으로 데이터를 송신할 수 있게 통합 인터페이스를 사용해야 한다.
  layered system	서버는 중간 서버를 통해 로드 밸런싱 등을 제공하여 확장성 등을 제공할 수 있어야 한다.
  self-descriptiveness	별도의 문서가 없어도 쉽게 이해할 수 있는 표현 구조(JSON, XML)와 정보를 가져야 한다.

method

• RFC7231
  • GET
    • 리소스 조회
    • 멱등(idempotent) 만족
    • 캐시 가능
  • HEAD
    • 응답에 본문을 보내면 안 된다는 점을 제외하면 GET과 동일
    • GET을 호출했을 때와 같은 헤더를 응답
    • 메타데이터를 얻을 때 사용
      • 리소스 존재 유무, 버전, 헬스체크 등
    • 멱등(idempotent) 만족
    • 캐시 가능
  • POST
    • 대상 리소스가 요청에 포함된 표현을 처리하도록 요청
    • RFC에 ‘Appending data to a resource’s existing representation(s).’ 표현이 있는데 생성 뿐만아니라 표현에 대한 추가도 가능한 것으로 해석됨
    • 206(Partial Content), 304(Not Modified), 416(Range Not Satisfiable)를 제외한 대부분의 상태 코드 응답 가능
    • 처리 결과가 기존 리소스와 동일하다면 Location 필드에 기존 리소스 식별자와 함께 303(See Other)를 응답하여 클라이언트가 해당 리소스로 리다이렉션 하게 할 수 있음
    • 멱등(idempotent)을 만족하지 않음
    • 캐시 가능
  • PUT
    • 대상 리소스가 생성되거나 기존 리소스를 대상 리소스로 대체되도록 요청
      • SQL의 INSERT INTO ON DUPLICATE KEY UPDATE와 같은 역할
      • 즉 클라이언트가 원하는 대상 리소스를 알고 있다는 가정
    • 멱등(idempotent) 만족
    • 캐시 불가능
    • PUT의 성공
      • PUT 이후 동일한 대상 리소스에 대해 GET 했을 때 동일한 리소스가 응답되는 것
      • 하지만 서버가 다른 사용자의 요청과 병렬 처리되거나 동적 처리로 인해 동일한 리소스가 응답되지 않을 수 있음
      • PUT의 성공 응답은 서버에 사용자의 의도가 전달 됬음을 의미
      • 201(Created), 200(OK), 204(No Content)를 응답
    • 서버는 해석이 안되는 헤더는 무시해야 함
      • 415(Unsupported Media Type)와 같은 상태 코드 응답 혹은 해석이 되는 헤더로 변환하여 처리
    • 400(Bad Request)을 응답할 수 있어야 한다
    • POST와의 차이점
      • POST
        • 대상 리소스가 요청에 포함된 표현을 처리
      • PUT
        • 대상 리소스의 상태를 대체
      • POST는 호출 횟수 만큼 리소스가 생성되지만 PUT은 여러번 호출하더라도 하나의 리소스에 대해서만 영향을 받음
  • DELETE
    • 리소스 삭제
    • 정확하게는 리소스 삭제를 기대하는 것이 아닌 uri 매핑에 대한 삭제를 기대
    • 멱등(idempotent) 만족
    • 캐시 불가능
    • 응답
      • 202(Accepted)
        • 성공 확률이 높지만 실행 전인 경우
      • 204(No Content)
        • 실행되었고 추가 정보가 제공되지 않은 경우
      • 200(OK)
        • 실행되었고 응답에 상태를 설명하는 표현이 포함된 경우
  • CONNECT
    • 원본 서버에 대한 터널을 설정하도록 요청
    • 성공할 경우 터널이 닫힐 때까지 양방향으로 패킷의 블라인드 포워딩으로 동작을 제한
    • 대부분의 원본 서버는 CONNECT method를 구현하지 않음
    • 멱등(idempotent)을 만족하지 않음
    • 캐시 불가능
  • OPTIONS
    • 요청 가능한 메소드 정보 요청
    • 멱등(idempotent) 만족
    • 캐시 불가능
  • TRACE
    • 요청 메시지의 어플리케이션 레벨 루프백을 요청
    • 멱등(idempotent) 만족
    • 캐시 불가능
• RFC5789
  • PATCH
    • REST를 제창한 Roy T. Fielding이 partial PUT이 RESTful 하지 않기 때문에 PATCH 만듬
    • 리소스 부분 수정
    • 구조
    • 멱등(idempotent)을 만족하거나 만족하지 않음
      • A PATCH request can be issued in such a way as to be idempotent,
    • 캐시 가능

status code