이 장에서는 일반적인 클라이언트 영역에서 고려해야 할 REST API 설계 원칙에 대해 설명한다.
버전을 정의하는 방법
REST API는 서로 연결된 리소스(리소스 모델)들의 조립으로 구성되어 있다. 각 리소스 버전은 표현 폼과 상태에 의해 전달된다.
규칙
새로운 개념을 도입하려면 새로운 URI를 사용해야 한다
- 리소스는 마치 어떤 사물에 대한 개념과 같은 일종의 의미론적인 모델이다
- 리소스의 표현 형식과 상태는 시간이 지나면서 변하지만, 식별자는 다른 URI로는 대치할 수 없는 ‘개념’을 일관되게 나타내야 한다.
표현 형태의 버전을 관리하기 위해서는 스키마를 사용해야 한다
REST API 리소스 표현의 형태 버전은 이를 관리하는 스키마 문서를 통해서 처리해야 한다
엔티티 태그(ETag)는 표현 상태 버전을 관리하기 위해 사용한다
- ETag는 리소스 표현 상태의 버전을 전달함
- 개별적인 리소스와 연관된 엔티티 태그값은 REST API의 가장 작은 단위의 버저닝 시스템이다.
보안
- REST API에서는 특정 클라이언트나 사용자와 관련된 리소스를 외부로 드러내는 경우가 많음
- 예를 들어, REST API의 도큐먼트에 개인 정보가 포함되거나 REST API의 컨트롤러에서 제한된 사용자만 수행하도록 의도한 처리 방법이 외부로 드러날 수 있음
- 아래 규칙들은 REST API의 민감한 리소스 보호에 대해 다룬다
리소스 보호를 위해 OAuth를 사용할 수 있다
- OAuth(Open Authorization)는 모든 클라이언트에 대해 일관된 접근을 사용해서 안전한 권한을 제공하는 공개 표준임
- 다른 사이트에 사용자 id나 비밀번호와 같은 개인 정보를 알려주지 않고, 저장된 사진이나 주소록과 같은 개인 리소스를 공유할 수 있도록 해주는 것으로 잘 알려져 있음
- OAuth는 HTTP 기반의 권한 프로토콜로서 리소스 보호가 가능함.
- 구조적으로
OAuth 프로토콜은 REST API가 클라이언트와 상호작용할 때 리소스 중심과 상태가 없는 점을 상호 보완하는 방법으로, 보안 문제의 해결을 도움
리소스 보호를 위해 API 관리 솔루션을 사용할 수 있다
API 리버스 프록시는 비교적 새로운 타입의 네트워크 기반 중간자로서, REST API의 자원을 보호하는 데 사용할 수 있다.
응답 표현 조합
- REST API 클라이언트의 요구 사항은 시간이 지남에 따라 변하게 되고, 새로운 기능이 추가되면 클라이언트는 지원하는 REST API에 새로운 리소스를 요청할 수 있다.
- REST API는 클라이언트를 배려하기 위한 방법으로 응답 표현의 조합을 제어할 수 있는 측정 방법을 제공함
- 아래 규칙은 REST API에서 리소스 모델을 일관성 있게 유지하면서 클라이언트의 요청에 맞춰 응답을 조절할 수 있는 방법을 제공함
규칙
URI의 쿼리 부분은 부분 응답을 지원할 때 사용해야 한다
- REST API는 클라이언트가 요청한 데이터보다 더 많은 정보를 포함하는 리소스 상태 모델을 제공해야 할 경우가 있다
- 대역폭을 절약하거나 전체적인 상호작용을 가능한 한 빠르게 하기 위해, REST API 클라이언트는 쿼리 부분의 fields 파라미터를 사용하여 응답 데이터를 줄일 수 있다.
# Request GET /students/morgan?fields=(firstName, birthDate) HTTP/1.1 Host: api.college.restapi.org # Response HTTP/1.1 200 OK Content-Type : application/json { "firstName": "Morgan", "birthDate": "1992-07-31" }
URI 쿼리 부분은 연결된 리소스(하이퍼텍스트 링크, 오브젝트, 이미지 등)를 포함할 때 사용해야 한다
# Request GET /students/morgan?embed=(favoriteClass) HTTP/1.1 # Response HTTP/1.1 200 OK Content-Type: application/json; { "firstName" : "Morgan", "birthDate" : "1992-07-31", "favoriteClass" : { "id": "japn-0301", "name": "Third-Year Japanese", "links": { "self" : { "href" : "http://api.college.restapi.org/classes/japn-301", "rel" : "http://api.relations.wrml.org/common/self" } } } }
클라이언트 영역
자바스크립트에서 여러 웹 사이트에 읽기/쓰기 접근이 가능하도록 CORS를 지원해야 한다.
- 교차 사이트의 리소스 공유(CORS : Cross-Origin Resource Sharing)는 W3C에서 제안한 웹브라우저에서 교차 사이트로 요청할 수 있도록 하는 방법임
- CORS는 JSONP를 대신할 수 있는 것으로 모든 요청 메서드를 지원할 수 있다