Restful API

RESTful API

• 6 원칙

  • Uniform Interface
    • URI로 지정한 리소스 조작을 통일되고 한정적인 인터페이스로 수행
  • Stateless(무상태성)
    • REST는 무상태성 성격(상태정보 저장/관리 X)
    • 자유도 증가 ~> 구현이 단순해짐
  • Cacheable(캐시 가능)
    • 웹의 인프라 활용 가능 ~> HTTP의 캐싱 기능 활용
    • HTTP 프로토콜 표준에서 사용하는 Last-Modified나 E-Tag를 활용한 캐싱
      • Last-Modifed는 E-Tag보다 부정확 ~> 예비용으로 활용
      • Last-Modifed에는 마지막 수정된 잘짜와 시각을 담고있음
      • E-Tag는 특정 버전의 리소스를 식별
      • E-Tag는 요청된 값을 ASCII 코드와 같이 고유한 형태로 표현
  • Client-Server 구조
    • REST 서버는 API 제공, 클라이언트는 사용자 인증과 컨텐스트 등을 직접 관리로 역할 분리 ~> 서로 의존성이 줄어들게 한다.
  • Hierarchical system(계층형 구조)
    • REST 서버는 다중 계층으로 구성
    • 보안, 로드 밸런싱, 암호화 계층 추가 ~> 구조상의 유연성
    • PROXY, 게이트웨이 같은 네트워크 기반 중간매체를 사용할 수 있게한다.
    • 역할을 분리해서 필요에 따라 추가한다는 의미로 이해했음
  • code on demand (Optional)
    • 서버가 네트워크를 통해 클라이언트에 프로그램 전달 ~> 클라이언트에서 실행될 수 있어야 한다.
    • 가시성이 감소하기 때문에 선택 사항

• RESTful하게 API를 디자인 한다는 것의 의미

  • 리소스와 행위를 명시적이고 직관적으로 분리

    • 리소스는 URI로 표시 ~> 명사로 표현
    • 행위는 HTTP Method로 표현 ~> 각각 분명한 목적으로 사용
      • GET(조회)
      • POST(삽입)
      • PUT(기존 entity 전체 수정)
      • PATCH(기존 entity 일부 수정)
      • DELETE(삭제)

  • Message는 Header와 Body를 명확하게 분리해서 사용

    • Entity에 대한 내용은 body에 담는다.

    • API 버전 정보, 응답 MIME 타입 등은 header에 담는다.

    • MIME 타입 => 전송된 문서의 다양성을 알려주는 메커니즘

      • 확장자는 의미 X, text/html, image/jpeg와 같은 타입 명시

      • 일반적으로 type/subtype으로 표현

      • multipart/form-data 멀티파트 문서형식도 자주 이용

      • POST / HTTP/1.1
        Host: localhost:8000
        User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9; rv:50.0) Gecko/20100101 Firefox/50.0
        Accept: text/html,application/xhtml+xml,application/xml;q=0.9,/;q=0.8
        Accept-Language: en-US,en;q=0.5
        Accept-Encoding: gzip, deflate
        Connection: keep-alive
        Upgrade-Insecure-Requests: 1
        Content-Type: multipart/form-data; boundary=---------------------------8721656041911415653955004498
        Content-Length: 465

        -----------------------------8721656041911415653955004498
        Content-Disposition: form-data; name="myTextField"

        Test
        -----------------------------8721656041911415653955004498
        Content-Disposition: form-data; name="myCheckBox"

        on
        -----------------------------8721656041911415653955004498
        Content-Disposition: form-data; name="myFile"; filename="test.txt"
        Content-Type: text/plain

        Simple file.
        -----------------------------8721656041911415653955004498--

    • MIME 스니핑

      • MIME 타입이 없을 때, 브라우저가 MIME 스니핑을 시도 ~> 리소스를 읽고 정확한 MIME타입 추측
      • 보안 관련된 문제가 발생 ~> Content-Type 중 X-Content-Type-Options를 전송해서 차단 가능

    • http header와 http body로 나누고, body에는 json 구조로 분리 가능

  • API 버전 관리

    • API 변경할 때는 하위 호환성을 보장해야한다.

  • 서버와 클라이언트가 같은 방식을 사용해서 요청하도록

    • 브라우저 ~> form-data submit, 서버 ~> json 처러 다르게 보내는 것이 아니라, 둘 다 json or form-data로 통일
    • 이를 URI가 플랫폼 중립적이라고 표현
    • 여러 플랫폼을 구별해야한다면 request header의 user-agent 값을 참조해서 구현

• URI 설계 시 주의할 점

  • 슬래시(/) 구분자는 계층 관계를 나타낼 때 표현, 마지막 URI에는 /를 포함하지 않음
  • 하이픈(-)은 URI 가독성을 높이는데 사용(_은 폰트에 따라 안보일 수 있으니 사용X)
  • URI 경로는 소문자로 구성(대문자는 피해라)
  • 파일 확장자는 URI에 포함 X (Accept header를 통해 확장자를 명시)

• 장점

  • Open API 제공에 용이
  • 멀티플랫폼 지원 및 연동에 용이
  • 원하는 타입으로 데이터 송수신
  • 기존 웹 인프라(HTTP)를 그대로 이용할 수 있음

• 단점

  • 사용할 수 있는 메소드가 HTTP Method가 전부
  • 분산 환경에서는 부적합
  • HTTP 통신 모델만 지원