Keepeek - 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 link
• fields=id,orientation,fileVersionCount embedded media only contains these 3 properties + a self link
• fields=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 links
• fields=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 fields
• fields=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 name
• fields=id,_embedded{updateUser} embedded media only a self link + an embedded update user with id, name and first name
• fields=id,_embedded{folders} embedded media only a self link + an embedded folders with id, name and self link

Warning: Some characters in URL have to be URL encoded for example _links{kpk:large,kpk:medium} has to be sent as _links%7Bkpk%3Alarge%2Ckpk%3Amedium%7D

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
        }]
    }
}