REST API

REST(Representational State Transfer) API

• WWW(World Wide Web)의 자원에 주소를 지정하고, 지정된 주소의 자원을 프로그래밍적으로 제어할 수 있게 만든 인터페이스

• 클라이언트-서버 간 메시지 교환을 통해 서로 통신

• 프로토콜 : 통신 간의 규약. 웹 상에서는 HTTP 프로토콜을 이용한다.

  • 인증,권한…. 다양한 메시지를 요청하고 수신한다.
  • 따라서 프로토콜이 짧고 단순할수록 네트워크의 부하 측면에서는 훨씬 유리하다
  • 또 프로토콜이 제각각이라면 관리하기 힘들어진다. - 약속을 통해 비슷한 구조를 유지한다.

• API : 서비스 간 주소와 메시지를 주고받기 위한 명세

• REST

  • 네트워크 아키텍처 원리의 모음

    • 네트워크 아키텍처 원리? 자원을 정의하고 자원에 대한 주소를 지정하는 방법 전반

    • 웹상의 자료를 HTTP위에서 SOAP이나 쿠키를 통한 세션트래킹 같은 별도의 전송 계층 없이 전송하기 위한 아주 간단한 인터페이스

      • SOAP(Simple Object Access Protocol)

        • HTTP,HTTPS,SMTP등을 통해 XML기반의 메시지를 컴퓨터 네트워크 상에서 교환하는 프로토콜

        • 웹 서비스에서 기본적인 메시지를 전달하는 기반

        • <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
          <SOAP-ENV:Body>
          <getProductDetails xmlns="http://warehouse.example.com/ws">
          <productId>827635</productId>
          </getProductDetails>
          </SOAP-ENV:Body>
          </SOAP-ENV:Envelope>
          

  • HTTP/WWW이 아닌 아주 커다란 소프트웨어 시스템 설계 가능

  • 리모트 프로시저 콜 대신 간단한 XML/HTTP인터페이스 이용 설계 가능

  • REST 인터페이스의 목표

    • 구성 요소 상호작용의 규모 확장성
    • 인터페이스 범용성
    • 구성 요소의 독립적 배포
    • 중간적 구성요소를 이용한 응답 지연 감소, 보안 강화, 레거시 시스템 캡슐화

REST의 특징

• Uniform
  • URI로 지정한 리소스에 대한 조작 통일, 한정적 인터페이스로 수행
• Stateless
  • 무상태성
  • 작업을 위한 상태정보를 따로 저장하고 관리하지 않는다.
  • 세션정보/쿠키정보를 별도로 저장/관리하지 않는다 - 들어오는 요청만 단순 처리
  • 서비스 자유도 높임, 구현이 단순해짐
• Cacheable
  • 기존 웹 표준을 그대로 사용하기 때문에 기존 웹 인터페이스 활용 가능
  • modified태그, e-tag를 이용한 캐싱 구현
• Self-descriptiveness(자체 표현 구조)
  • REST API 메시지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조
• Client-server
  • REST서버: API 제공 / 클라이언트: 사용자 인증, 컨텍스트(세션,로그인정보)직접 관리
  • 클라이언트와 서버에서 개발해야 할 내용이 명확, 서로간 의존성 감소
• layered structure
  • 다중 계층으로 구성, 구조상의 유연성 증가
  • 로드밸런싱,암호화 계층 추가
  • proxy, 게이트웨이 등 네트워크 기반의 중간매체 사용 가능

REST 디자인 가이드

• URI는 정보의 자원을 표현해야 한다

  • 리소스명은 동사보다 명사 사용

  DELETE /members/1
  

• 자원에 대한 행위는 HTTP Method(GET/POST/PUT/DELETE)로 표현한다

  • HTTP Method의 알맞은 역할?

    METHOD	역할
    POST	리소스를 생성한다
    GET	해당 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져온다
    PUT	해당 리소스를 수정한다
    DELETE	리소스를 삭제한다

URI 설계시 주의할 점

• 슬래시 구분자는 계층 관계를 나타내는 데 사용

  http://example.com/animals/mammals/whales
  

• URI 마지막 문자로 슬래시(/)를 포함하지 않는다.

  http://example.com/animals/mammals/whales/	(X)
  http://example.com/animals/mammals/whales	(O)
  

• 불가피하게 긴 URI경로 사용시 하이픈(-)을 사용, 가독성 높임

• 밑줄(_)은 URI에 사용하지 않는다(가독성)

• URI경로에는 소문자가 적합

• 파일 확장자는 URI에 포함시키지 않는다.

  • accept header 이용

    GET /members/soccer/345/photo HTTP/1.1 Host:example.com Accept: image/jpg
    

리소스간 관계 표현 방법

/리소스명/리소스ID/관계있는 다른 리소스명

GET: /users/{userid}/devices (일반적으로 소유관계 표현시)

자원 표현 - Collection, Document

• document : 문서/ 한 객체

• collection: 문서/객체의 집합

• 모두 리소스라고 표현할 수 있으며, URI에 표현된다.

  http://example.com/sports/soccer/players/12
  

  sports, players 컬렉션 / soccer,12 도큐먼트

HTTP 응답 상태 코드

추가 참고: 위키피디아: HTTP 상태 코드

출처

REST API 제대로 알고 사용하기

위키피디아: REST