REST API 디자인 규칙 - 6장

6-1. 개요

• 어떤 것이라도 REST API의 클라이언트가 될 수 있고, REST API는 클라이언트 프로그램이 필요로 하는 것이 무엇이든 간에 필요를 맞춰주기 위해 설계된다.

6-2. 버전을 정의하는 방법

• 규칙 :
  • 새로운 개념을 도입하려면 새로운 URI를 사용해야 한다.
    • v2와 같이 버전을 표시하는 것을 URI에 포함하면 개념 자체가 여러 버전이 있다는 것을 나타내는데, 이렇게 되는 것을 의도하지는 않는다.
    • URI에 대해 개념적으로 변함없는 리소스를 매핑해야 한다. 새로운 개념을 드러내고자 할 때만 새로운 URI를 도입해야 한다.
  • 표현 형태의 버전을 관리하기 위해서는 스키마를 사용해야 한다.
    • 미디어 타입 스키마 버저닝 → 스키마 문서를 통해서 처리한다.
  • 엔티티 태그는 표현 상태 버전을 관리하기 위해 사용한다.
    • Etag는 리소스 표현 상태 버전을 전달하며 이를 활용한다.

6-3. 보안

• 민감한 리소스 보호에 대해 다룬다.
• 규칙
  • 리소스 보호를 위해 OAuth를 사용할 수 있다.
    • OAuth는 모든 클라이언트에 대해 일관된 접근을 사용해서 안전한 권한을 제공하는 공개 표준이며, HTTP 기반의 권한 프로토콜로서 리소스 보호가 가능하다.
  • 리소스 보호를 위해 API 관리 솔루션을 사용할 수 있다.
    • API 리버스 프록시 : 비교적 새로운 타입의 네트워크 기반 중간자로서, REST API 자원을 보호하는데 사용할 수 있다. (Apigee, Mashery 같은 솔루션 제공 업체)

6-4. 응답 표현 조합

• REST API에서 리소스 모델을 일관성 있게 유지하면서 클라이언트의 요청에 맞춰 응답을 조절할 수 있는 방법을 제공한다.
• 규칙
  • URI의 쿼리 부분은 부분 응답을 지원할 때 사용해야 한다.
    • 클라이언트가 요청한 데이터보다 더 많은 정보를 포함하는 리소스 상태 모델을 제공해야 할 경우, 대역폭 절약하거나 전체적인 상호작용을 가능한 한 빠르게 하기 위해 쿼리 파라미터에 fields 파라미터를 사용하여 응답 데이터를 줄일 수 있다.
    • fields 쿼리 파라미터를 이용해서 특정한 일부분을 요청하거나 제외하고 요청하도록 설정하여 사용할 수 있다.
    • embed 쿼리 파라미터를 이용해서 fields로서 응답 표현에 직접적으로 표현하고자 하는 링크 관계를 식별할 수 있다.
  • URI 쿼리 부분은 연결된 리소스를 포함할 때 사용해야 한다.

6-5. 하이퍼미디어 처리

6-6. 자바스크립트 클라이언트

• 규칙 :
  • 자바스크립트에서 여러 웹 사이트에 읽기 접근이 가능하도록 JSONP를 지원해야 한다.
  • 자바스크립트에서 여러 웹 사이트에 읽기/쓰기 접근이 가능하도록 CORS를 지원해야 한다.
    • CORS (Access-Control-Allow-Origin) 헤더를 사용해서 리소스에 대한 교차-사이트 접근을 허용하도록 한다.