REST API

Special HTTP Headers

Updated: July 17, 2023

Here are HTTP headers that you can use to have more control with REST API Calls.

X-NXVoidOperation

Possible values: "true" or "false". If not specified the default is "false"

This header can be used to force the server to assume that the executed operation has no content to return (a void operation). This can be very useful when dealing with blobs to avoid having the blob output sent back to the client.

For example, if you want to set a blob content on a document using the Blob.Attach operation, after the operation execution the blob you sent to the server is sent back to the client (because the operation is returning the original blob). This behavior is useful when creating operation chains but when calling such an operation from remote it will use more network traffic than necessary.

To avoid this, use the header: X-NXVoidOperation: true

Example:

POST /nuxeo/site/automation/Blob.Attach HTTP/1.1
Accept: application/json+nxentity, */*
Content-Type: multipart/related;
    boundary="----=_Part_0_130438955.1274713628403"; type="application/json+nxrequest"; start="request"
Authorization: Basic QWRtaW5pc3RyYXRvcjpBZG1pbmlzdHJhdG9y
X-NXVoidOperation: true
Host: localhost:8080

------=_Part_0_130438955.1274713628403
Content-Type: application/json+nxrequest; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: request
Content-Length: 75

{"params": {"document":"/default-domain/workspaces/myws/file"}, "context":{}}

------=_Part_0_130438955.1274713628403
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
Content-Disposition: attachment; filename=test.jpg
Content-ID: input

[binary data comes here]

------=_Part_0_130438955.1274713628403--

Nuxeo-Transaction-Timeout

This header can be used when you want to control the transaction duration. As an example, if you want to inject a large blob in the repository, the default transaction timeout may be not enough. You can specify a 5 minutes timeout for the chain you're executing:

Nuxeo-Transaction-Timeout: 300

X-NXproperties

Available since 7.2 to replace X-NXDocumentProperties.

This header can be used whenever a Document will be returned by the server. The header forces the server to fill up the returned document with data from schemas that matches the X-NXproperties filter. So, X-NXproperties is a filter of schemas. If you don't use the header, all properties of the document are returned.

To have more properties in the returned document, you can specify a list of document schema names:

X-NXproperties: dublincore, file

or to have all the document content, you can use the * character as the filter value or you can simply skip the header definition:

X-NXproperties: *

X-NXRepository

This header can be used when you need to access a specific repository. The default value is "default", as it's the default repository name in the Nuxeo Platform. This is handy if you have changed the default name or if you have multiple repositories.

X-NXRepository: myCustomRepositoryName

X-NXenrichers.document

Available since 7.2 to replace X-NXContext-Category.

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 instance, when specifying X-NXenrichers.document = "thumbnail", the JSON payload of the document REST calls response contains the related attached file thumbnail of the document. You can add several content enrichers into the header separated by comma. (Content Enrichers listing)

X-NXenrichers.document: "thumbnail"

X-Versioning-Option

This header can be used when you need to increment the minor or major version and return the versioned document. (Since 5.9.5) By default, no version checkin is done and 'live' (snapshot) document is returned. This is handy if you have to update the document while incrementing the version for instance.

Accepted values are MAJOR, MINOR or NONE.

X-Versioning-Option: MAJOR

X-NXfetch.document

This header can be used to load additional parts of an object whose entity-type is document.

X-NXfetch.document: value1,value2,...

Value could be:

  • versionLabel: Loads the versioning information
  • lock : Loads the lock owner and the lock date
  • properties: Loads every properties associated with a resolver and having a marshaller registered
  • Any field name (dc:creator, dc:subjects): Loads the given field if it's associated with a resolver and the related entity has a marshaller registered. For example, dc:creator would be loaded because it references a user and a user marshaller is provided by the Nuxeo Platform. Built-in fetchable properties are dc:creator, dc:contributors, dc:lastContributor, dc:subjects, dc:coverage, dc:nature.

More details about properties you can fetch here: Document JSON and Extended Fields

depth

This header can be used to control the aggregation depth.

Accepted values are:

  • root: Loads only the root element, does not load any enricher or fetched properties.
  • children: Loads the root document and one level of enricher or fetched properties.
  • max: Load the root, one level of enricher and fetched properties. And for each loaded children, loads one level of enricher or fetched properties.
depth: children

More details about the control of the depth here: Aggregating Marshallers and Avoiding Infinite Loops


Related Documentation