If no identifier is specified in the request, such as /resource, then response will be a List response. The List format will be used even if the list contains only one item. If the list is empty, you will still receive a response in the List format with an empty _list array.

Data Model

The List data model is adapted from the HAL specification.

Data Model

NameTypeDescription
_links_links

List of links that may be used to interact with the list, such as a link to the next page, last page, etc.

_metadata_metadataAdditional metadata describing the list, such as a count of the records in the list.
_listarrayAn array of the items in the list. The type of item is determined by the resource requested.

Examples

Consider a request for a list of pets. The response may look something like this.



{
	"_links": {
		"self": {
			"href": "https://www.example.com/api/v2/pets",
			"class": "pets"
		}
	},
	"_metadata": {
		"count": 2
	},
	"_list": [
		{
			"_list": {
				"self": {
					"href": "https://www.example.com/api/v2/pets/1",
					"class": "pets",
					"identifier": "1"
				},
			"_metadata": {
				"created": "2018-09-30T23:11:17Z",
				"lastModified": "2018-10-01T02:19:22Z"
			},
			"petId": 1,
			"type": "dog",
			"name": "Fido"
		},
		{
			"_links": {
				"self": {
					"href": "https://www.example.com/api/v2/pets/2",
					"class": "pets",
					"identifier": "2"
				},
			"_metadata": {
				"created": "2018-10-01T06:41:19Z",
				"lastModified": "2018-10-01T06:41:19Z"
			},
			"petId": 2,
			"type": "cat",
			"name": "fluffy"
		}
	]
}




_links

List of links that can be used to interact with the collection. Only links that are valid for the current state of the collection will be included in the response.

 



"self": {
	"href": "https://www.example.com/api/v2/pets",
	"class": "pets"
}




_metadata

Metadata is information about the state of a the list itself. 

Examples of metadata are things like the count of items returned in the list. This will also include information for pagination, when implemented, such as page count, number of pages, etc.

NameTypeDescription
countnumberCount of the items in the list that match the search criteria. If paginated, this is the count of the entire list, not the count of items in this response.

Examples



"_metadata": {
	"count": 2
}




 

List style response for requests which may return multiple items