메시지 바디 포맷
규칙
JSON 리소스 표현을 지원해야 한다
- JSON은 자바스크립트의 장점을 활용하여 웹 브라우저의 런타임 환경과 통합해 사용할 수 있다
- 특정 리소스 타입에 대한 표준 포맷이 없을 경우, REST API는 그 정보를 구조화하기 위해서 JSON 포맷을 사용해야 함
- JSON은 REST API 설계에서 널리 사용되는 대중적인 포맷
- 이는 오직 JSON 데이터 포맷에 해당하는 규칙으로, application/json 미디어 타입을 HTTP 메시지의 Content-Type 헤더 값으로 반드시 사용해야 한다는 의미는 아님
JSON은 문법에 잘 맞아야 한다
- JSON에서 이름을 붙일 때는 소문자를 섞어서 사용해야 하고, 특수 문자는 피해야 함
XML과 다른 표현 방식은 선택적으로 지원할 수 있다
REST API는 xml, html 등의 리소스를 표현하기 위해 선택적으로 대체 포맷을 사용하여 다른 언어를 지원할 - 수 있다
추가 봉투는 없어야 한다(message envelope)
REST API는 HTTP가 제공한 메시지 봉투를 이용해야 한다. 즉, 바디는 추가적인 wrapper 없이 리소스 상태의 표현을 포함해야 함
하이퍼미디어 표현
규칙
링크는 일관성된 형태로 나타내야 한다
링크 관계를 표현할 때에는 일관된 형태를 사용해야 한다
링크를 표현할 때는 일관된 형태를 사용해야 한다
응답 메시지 바디 표현에 셀프 링크를 포함해야 한다
진입 API URL 수를 최소화하라
- REST API 설계 관점에서 웹을 보면, 홈페이지와 그와 연관된 웹 사이트 내비게이션이 도처에 있음 을 고려해야 함
- API Docroot의 URI에서 사람이 읽을 수 있는 형태의 문서를 제공하는 것이 곧 REST API 다
리소스의 상태에 따라 가능한 액션을 표현하기 위해서 링크를 사용해야 한다
REST의 HATEOS(Hypermedia as the Engine of Application State) 제한 조건은, 클라이언트의 모든 요청에 대해 API는 상태에 민감한 링크를 포함하는 리소스 표현으로 응답해야만 한다는 것임
미디어 타입 표현
미디어 타입 format은 일관성 있는 폼을 사용해야 한다
미디어 타입 스키마를 표현할 때는 일관성 있는 형식을 사용해야 한다
오류 표현
HTTP 4xx와 HTTP 5xx 오류 상태 코드는 응답 메시지 엔티티 바디 안에 클라이언트가 읽을 수 있는 정보를 추가해야 함
오류는 일관성 있게 표현한다
{ "id" : Text, // 오류 타입에 대한 유일한 ID/code임. 클라이언트는 id를 사용해 // 어떤 종류의 오류가 발생했는지, 그에 따라 어떻게 행동/메시지해야 하는지 이해함 "description": Text // 선택사항인 오류 설명 }
오류 응답은 일관성 있게 표현한다
요청을 처리할 때 하나 이상의 오류가 발생하면 메시지 바디 안에 오류 응답 표현을 반환한다
{ "elements" : [ { "id": "Update Failed", "description": "Failed to update /users/1234", } ] }
일반적인 오류 상황에서는 일관성 있는 오류 타입을 사용해야 함
API의 다양성으로 말미암아 일반적 오류 타입은 중요해진다.
오류 타입은 한 번 정의되면 서비스를 제공하는 오류 스키마 문서를 통해 모든 API에 공유되어야 한다.