Pluggable Context
It is sometimes useful to optimize the number of requests you send to the server. For that reason we provide a mechanism for requesting more information on the answer, simply by specifying the context you want in the request header.
For example, it is some times useful to get the children of a document while requesting that document. Or its parents. Or its open related workflow tasks.
The blog post "How to Retrieve a Video Storyboard Through the REST API" gives an example of how to use this mechanism and the dedicated extension point (Since 5.9.5, "rest contributor" has been renamed "content enricher"):
<extension target="org.nuxeo.ecm.automation.io.services.enricher.ContentEnricherService" point="enricher">
<enricher name="name" class="namespace">
</enricher>
</extension>
You can add several content enrichers into the header separated by comma
Default Content Enrichers
Thumbnail
When specifying X-NXContext-Category = “thumbnail”, the JSON payload of the document REST calls response contains the related attached file thumbnail of the document:
Request URL:
http://localhost:8080/nuxeo/api/v1/id/889cebf8-1704-45d5-99de-9f540d9b6655
Request Method:
GET
Request Headersview source
...
Content-type:
application/json+nxentity
X-NXContext-Category:
thumbnail
X-NXDocumentProperties:
dublincore
{
"entity-type": "document",
"repository": "default",
"uid": "889cebf8-1704-45d5-99de-9f540d9b6655",
"path": "/default-domain/workspaces/workspace/image",
"type": "Picture",
"state": "project",
"versionLabel": "0.0",
"isCheckedOut": true,
"title": "image",
"lastModified": "2014-07-15T16:38:42.80Z",
"properties": {
"dc:description": "",
...
},
"facets": [
"Versionable",
...
],
"changeToken": "1405442322802",
"contextParameters": {
"thumbnail": {
"url": "http://localhost:8080/nuxeo/nxthumb/default/889cebf8-1704-45d5-99de-9f540d9b6655/thumb:thumbnail/Small_photo.jpg"
}
}
}
ACLs
When specifying X-NXContext-Category = “acls”, the JSON payload of the document REST calls response contains all related ACLs of the document:
Request URL:
http://localhost:8080/nuxeo/api/v1/id/889cebf8-1704-45d5-99de-9f540d9b6655
Request Method:
GET
Request Headers
...
Content-type:
application/json+nxentity
X-NXContext-Category:
acl
X-NXDocumentProperties:
dublincore
{
"entity-type": "document",
"repository": "default",
"uid": "889cebf8-1704-45d5-99de-9f540d9b6655",
"path": "/default-domain/workspaces/workspace/image",
"type": "Picture",
"state": "project",
"versionLabel": "0.0",
"isCheckedOut": true,
"title": "image",
"lastModified": "2014-07-15T16:38:42.80Z",
"properties": {
"dc:description": "",
...
},
"facets": [
"Versionable",
...
],
"changeToken": "1405442322802",
"contextParameters": {
"acls": [
{
"name": "inherited",
"ace": [
{
"username": "Administrator",
"permission": "Everything",
"granted": true
},
{
"username": "members",
"permission": "Read",
"granted": true
}
]
}
]
}
}
Preview
When specifying X-NXContext-Category = “preview”, the JSON payload of the document REST calls response contains the related attached file preview of the document:
Request URL:
http://localhost:18090/api/v1/repo/test/path/folder_1/note_0
Request Method:
GET
Request Headersview source
...
Content-type:
application/json+nxentity
X-NXContext-Category:
preview
X-NXDocumentProperties:
dublincore
{
"entity-type": "document",
"repository": "default",
"uid": "efe571a9-b211-47d4-9358-ad1aa1ceaa4d",
"path": "/folder_1/note_0",
"type": "Note",
"state": "project",
"versionLabel": "0.0",
"isCheckedOut": true,
"title": "image",
"lastModified": "2014-07-15T16:38:42.80Z",
"properties": {
"dc:description": "",
...
},
"facets": [
"Versionable",
...
],
"changeToken": "1405442322802",
"contextParameters": {
"preview": {
"url": "http://localhost:8080/nuxeo/restAPI/preview/test/efe571a9-b211-47d4-9358-ad1aa1ceaa4d/default/"
}
}
}
Parameterized Content Enrichers
Some content enrichers might require some form of parameterization to better adjust to each use case.
These parameters are set during the content enricher's initialization and must be declared in the contribution:
<enricher name="myenricher" class="...">
<category>mycategory</category>
<parameter name="param1">value1</parameter>
<parameter name="param2">value2</parameter>
</enricher>
Vocabulary
This enricher adds the labels for each value of a property referencing a vocabulary.
To enable it for a given property two parameters must be set in the contribution:
- field: the xpath of the property holding the values to process
- directoryName: the name of the directory to get the labels from
For each vocabulary backed property an enricher must be set up. For example, to allow retrieving labels from the l10nsubjects directory:
<enricher name="l10nsubjects" class="org.nuxeo.ecm.automation.io.services.enricher.VocabularyEnricher">
<category>vocabularies</category>
<parameter name="field">dc:subjects</parameter>
<parameter name="directoryName">l10nsubjects</parameter>
</enricher>
Then, when specifying X-NXContext-Category = “vocabularies” , the JSON payload of the document REST calls response contains all the labels for each value of dc:subjects:
{
"entity-type": "document",
"repository": "default",
"uid": "efe571a9-b211-47d4-9358-ad1aa1ceaa4d",
"path": "/folder/note",
"type": "Note",
"state": "project",
"versionLabel": "0.0",
"isCheckedOut": true,
"title": "Note",
"lastModified": "2014-07-15T16:38:42.80Z",
"properties": {
"dc:description": "",
...
},
"facets": [
"Versionable",
...
],
"changeToken": "1405442322802",
"contextParameters": {
"l10nsubjects": {
"dc:subjects": [
{"id":"art/cinema","label_en":"Art/Cinema","label_fr":"Art/Cinéma"}
]
}
}
}
Note that the key used in contextParameters is the enricher's name and not the category. This allows using multiple vocabulary content enrichers with a single category.