Partial response
In order to limit network bandwith consumption or to retrieve specific properties, Keepeek API support a partial response mechanism based on the fields
query string.
Partial response feature is supported by all media collection resources (media-search, folder's medias, folder tree node's medias, basket's medias...)
This query string syntax is based on the following grammar:
&fields = properties
properties
: property
( , property
...) <-- select properties on the root json object (media)
property
: identifier
[ { properties
} | . function
] <-- select child object properties or filter items if property is an array
function
: byId( param
( , param
...) ){ properties
} <-- specify array filter function parameters
Syntax sample:
fields=id,width,height
embedded media only contains these 3 properties + a self linkfields=id,orientation,fileVersionCount
embedded media only contains these 3 properties + a self linkfields=id,_links{kpk:large,kpk:medium}
embedded media only contains the id property and the links sub object contains self link + the 2 requested thumbnail linksfields=id,_embedded{metadata.byId(title,legend,shot_date)}
embedded media only a self link + an embedded metadata array filtered on title, legend and shot_date form fieldsfields=id,_embedded{label.byId(1,2)}
embedded media only a self link + an embedded label array filtered on label ids 1 and 2 (Only id and label name displayed)fields=id,_embedded{label}
embedded media only a self link + an embedded labels array with all labels in the media (Only id and label name displayed)fields=id,_embedded{importUser}
embedded media only a self link + an embedded import user with id, name and first namefields=id,_embedded{updateUser}
embedded media only a self link + an embedded update user with id, name and first namefields=id,_embedded{folders}
embedded media only a self link + an embedded folders with id, name and self link
Notice: Valid identifier of media field can be found in the canonical representation of a media:
{
"id": 63,
"title": "Spirale",
"width": 1024,
"height": 683,
"resolution": 240,
"orientation": "LANDSCAPE",
"mediaType": "image/jpeg",
"fileSize": 327094,
"fileSizeString": "327 Ko",
"originalFileName": "©Alforesm - 29 décembre 2007.jpg",
"creationDate": "2012-08-27T22:00:00.000Z",
"updateDate": "2012-10-11T22:00:00.000Z",
"fileVersionCount": 1,
"_links": {
[...]
},
"_embedded": {
"metadata": [{
"id": "title",
"name": "Titre",
"value": "Spirale",
"_links": {
"kpk:field": {
"href": "http://baobab.keepeek.com/api/dam/forms/1/fields/2"
}
}
},
{
"id": "shot_date",
"name": "Date de prise de vue",
"value": "2007-12-28T23:00:00.000Z",
"_links": {
"kpk:field": {
"href": "http://baobab.keepeek.com/api/dam/forms/1/fields/5"
}
}
},
{
"id": "legend",
"name": "Légende",
"value": "Escalier de pierre en colimaçon",
"_links": {
"kpk:field": {
"href": "http://baobab.keepeek.com/api/dam/forms/1/fields/147"
}
}
},
[...]
}],
"importUser": {
"id": 16,
"lastName": "Dupont",
"firstName": "Jean"
},
"updateUser": {
"id": 24,
"lastName": "Durant",
"firstName": "Paul"
}
}
In this example valid field identifier are the properties of the media JSON object and the id of the metadata embedded fields:
- id
- title
- width
- height
- ...
- shot_date
- legend
- ...
/!\ Some fields in the metadata may not be available as search field, check in the form definition. for convenience, a link targeting the field configuration in the media form is provided. For example the legend field is indexed:
GET http://baobab.keepeek.com/api/dam/forms/1/fields/147
[...]
HTTP/1.1 200 OK
Content-Type: application/hal+json;version=1;charset=UTF-8
[...]
{
"id": "legend",
"title": "Légende",
"type": "TEXT_AREA",
"mandatory": false,
"indexed": true,
"indexSuggest": true,
"forceSelection": false,
"_links": {
"self": {
"href": "http://baobab.keepeek.com/api/dam/forms/1/fields/147"
},
"curies": [{
"name": "kpk",
"href": "http://baobab.keepeek.com/api/doc/rels/{rel}",
"templated": true
}]
}
}