RESTful 서비스 - 클라이언트가 자원 속성에 대해 유효한 값을 찾는 방법은 무엇입니까?

Question

RESTful API에서 제공하는 리소스에 대한 기능 검색의 일부로 서비스에서 허용 된 값을 알리는 방법을 찾고 있습니다.

GET /apples/17 

이 요청 수익률 :

{ 
    "name": "My yummy apple", 
    "color": "green" 
} 

클라이언트가 color 값이 때 예를 들어 PUT 팅 새로운 버전의 유효을 이해하기위한 apple 자원 속성 color을 가지고 다음의 예를 살펴 보자 이 사과는 여러 가지 방법으로 생각할 수 있습니다. 그러나 여기서는 모범 사례를 찾지 못했습니다. HTTP OPTIONS 동사가이 세분화 된 발견을 위해 만들어지지 않은 것 같습니다. 난 그냥 /apples 컬렉션에 배열 속성을 추가해야합니다 :

GET /apples 

응답 :

{ 
    ... 
    "colorValues": ["red", "green"] 
} 

이 더 나은 그리고 더 일반적으로 사용되는 방법이 있습니까?

편집 : 모든 "실제"리소스에 대한 스키마 리소스를 추가하는 것이 가능한 한 가지 방법을 깨달았습니다. 어떤 것이 apple 리소스에 대한 JSON 스키마 표현을 산출하는 GET /schemas/apple을 좋아했습니다. json-schema.org의 수정 된 예 :

{ 
    "id": "http://foo.bar/schema#", 
    "$schema": "http://json-schema.org/draft-04/schema#", 
    "description": "schema for an apple resource", 
    "type": "object", 
    ... 
    "colorValues": { 
     "enum": [ "red", "green" ] 
    } 
} 

이 예제는 아직 발견되지 않았습니다.

Answer 1

JSON 하이퍼 스키마는 이러한 종류의 작업에 적합합니다.

GET /apples/17 

-

HTTP/1.1 OK 
Content-Type: application/json; profile="/schema/apple" 

{ 
    "id": 17, 
    "name": "My yummy apple", 
    "color": "green" 
} 

클라이언트는 다음 schema/apple에서 하이퍼 스키마를 역 참조 링크가 다음에 수행 할 수 있습니다 무엇을 배울 수 있습니다.

GET /schema/apple 

-

HTTP/1.1 OK 
Content-Type: application/schema+json 

{ 
    "id": "http://foo.bar/schema/apple", 
    "$schema": "http://json-schema.org/draft-04/hyper-schema#", 
    "type": "object", 
    "properties": { 
    "id": { "type": "string", "readOnly": true }, 
    "name": { "type": "string" }, 
    "color": { "enum": ["red", "green"] } 
    }, 
    "required": ["id", "name", "color"], 
    "links": [ 
    { "rel": "self", "href": "/apple/{id}" }, 
    { 
     "rel": "http://foo.bar/relation/edit", 
     "href": "/apple/{id}", 
     "method": "PUT", 
     "schema": { "$ref": "#" } 
    } 
    ] 
} 

이것은 당신이 잘 알고있는 같은 JSON 스키마이지만,이 리소스에서 따를 수있는 링크를 설명하는 추가 키워드 links가 포함되어 있습니다. 클라이언트는 원본 JSON 데이터의 값을 사용하여 href URI 템플릿을 평가합니다. 그래서,이 경우, 링크가

{ 
    "rel": "http://foo.bar/relation/edit", 
    "href": "/apple/17", 
    "method": "PUT", 
    "schema": { "$ref": "#" } 
} 

이 링크 { "$ref": "#" }이 스키마를 의미한다 (이 /apple/17에 PUT 요청을 할 수 있으며, 요청 본문 /schema/apple에서 스키마에 대해 유효성을 검사해야하는 클라이언트를 지시 할 ... 평가).

이렇게하면 사람이 읽을 수 있고 기능에 대한 기계 실행 가능 설명을 모두 얻을 수 있습니다. 기존 클라이언트를 손상시키지 않고 API에 변경 사항을 적용 할 수 있기 때문에 기계 실행 부분은 큰 문제입니다.

참고 :이 코드는 JSON Hyper-Schema draft-04로 작성되었습니다. 최근에 나온 새로운 버전 초안 -05가 있습니다. 논쟁의 여지가있는 몇 가지 변화가 있습니다. 나는 여전히 초안 04를 추천하고있다. 사양은 https://tools.ietf.org/html/draft-luff-json-hyper-schema-00에서 찾을 수 있습니다.

Answer 2

가능한 방법 중 하나는 apples과 colours의 두 가지 리소스를 사용하는 것입니다. 잠재 고객이 사용 가능한 색상을 안정적으로 얻는 것은 매우 쉽습니다. 하이퍼 미디어는? many standards이 있지만 직접 만들 수도 있지만 널리 사용되는 방법을 고수하는 것이 좋습니다. 예를 들어

, 당신은 사과 모양을 받고,이 HAL 다음 구현하려는 경우 :

GET /apples/17 

{ 
    "name": "My yummy apple", 
    "_links": { 
    "self": { 
     "href": "/apples/17" 
    }, 
    }, 
    "colour": { 
    "id": "green", 
    "href": "/colours/green" 
    } 
} 

그리고 무엇 모든 색상 목록에 대해? 이 같은 STH :

GET /colours 

{ 
    "_links": { 
    "self": { 
     "href": "/colours" 
    } 
    }, 
    "_embedded": { 
    "colours": [ 
     { 
     "_links": { 
      "self": { 
      "href": "/colours/green" 
      } 
     }, 
     "id": "green" 
     }, 
     { 
     "_links": { 
      "self": { 
      "href": "/colours/red" 
      } 
     }, 
     "id": "red" 
     } 
    ] 
    } 
} 

그것은 예를 들면 채택 API를 디자인하는 현대적인 방법

아마존 AppStream 웹 서비스 Amazon으로는 하이퍼 텍스트 응용 프로그램 언어 (HAL)를 사용하는 자원 기반의 API입니다. HAL은 API의 리소스와 관계를 하이퍼 링크로 표현하는 표준 방법을 에 제공합니다. HAL을 사용하면 HTTP 메서드 (GET, PUT, POST, DELETE)를 사용하여 요청을 제출하고 응답의 API에 대한 정보를 수신합니다. 응용 프로그램은 반환 된 정보를 사용하여 API의 기능을 탐색 할 수 있습니다.

편집 :

GET /apples/17 

{ 
    "name": "My yummy apple", 
    "_links": { 
    "self": { 
     "href": "/apples/17" 
    }, 
    "available_colours": { 
     "href": "/apples/17/available_colours" 
    } 
    }, 
    "colour": { 
    "id": "green", 
    "href": "/colours/green" 
    },  
    "_embedded": { 
    "available_colours": [ 
     { 
     "_links": { 
      "self": { 
      "href": "/colours/green" 
      } 
     }, 
     "id": "green" 
     }, 
     { 
     "_links": { 
      "self": { 
      "href": "/colours/red" 
      } 
     }, 
     "id": "red" 
     } 
    ] 
    } 
} 

같은 다른 색상이 다른 기관에 허용하는 경우

, 당신이 할 수있는 STH 당신은 매우 유연한 구조이다시피.