REST API

Content Enricher

Updated: October 16, 2020

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 = &ldquo;thumbnail&rdquo;, the JSON payload of the document REST calls response contains the related attached file thumbnail of the document:

Call Example

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

Json Response Example

{
    "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 = &ldquo;acls&rdquo;, the JSON payload of the document REST calls response contains all related ACLs of the document:

Call Example

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

Json Response Example

{
    "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 = &ldquo;preview&rdquo;, the JSON payload of the document REST calls response contains the related attached file preview of the document:

Call Example

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

Json Response

{
    "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 = &ldquo;vocabularies&rdquo; , the JSON payload of the document REST calls response contains all the labels for each value of dc:subjects:

Json Response

{
    "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.