Icon

This documentation refers to the latest Fast Track version of the Nuxeo Platform (more information about Nuxeo release cycle).
Check if the page exists in the Nuxeo Platform LTS documentation.

Skip to end of metadata
Go to start of metadata
Nuxeo REST API is available on a Nuxeo server at the following URL: http://localhost:8080/nuxeo/api/v1/*. This section describes all the mechanisms that are offered by our REST API as well as all the tools useful for using it (clients, format of queries, etc.).
Icon

Before Nuxeo Platform 5.9.3, you need to install the REST API module available:

  • from the Marketplace,
  • from the Update Center of your Nuxeo Platform instance,
  • from the configuration wizard when you start your Nuxeo Platform instance for the first time.

Since Nuxeo Platform 5.9.3, the REST API is included in the default Nuxeo Platform.

Concepts

Nuxeo provides a complete API accessible via HTTP and also provides client SDKs in Java, JavaScript, Python, PHP, iOS and Android. This API is the best channel to use when you want to integrate remotely with the Nuxeo repository: Portals access, workflow engines, custom application JavaScript based, etc. This API has several endpoints:

  • Resources endpoints, for doing CRUD on resources in a 100% REST style.
    Multiple resources are exposed via this API (See the reference documentation page for the existing REST URLs and JSON resources):
    • Documents (/nuxeo/api/v1/id/{docId} or /nuxeo/api/v1/path/{path} ): to do CRUD on documents (including paginated search);
    • Users (/nuxeo/api/v1/user/{userId}): to do CRUD on users;
    • Groups (/nuxeo/api/v1/group/{groupId}): to do CRUD on groups;
    • Directories (/nuxeo/api/v1/directory/{directoryId}):  to do CRUD on directories;
    • Automation (/nuxeo/api/v1/automation/{Operation id}): to call a "command", i.e. an operation or chain of operations deployed on the server. This is the main way of exposing the platform services remotely;
    • Workflow and Task endpoints are to be implemented soon!
  • A commands endpoint, that exposes all the operations of the Automation module offering more than 100 commands for processing remotely the resources. The framework makes it very easy to add a new Java custom operation for completing the API if you miss something, and to chain operations server-side using Nuxeo Studio, so as to expose a coarse-grained API that fits your business logic.

The Nuxeo REST API offers several nice additional features compared to a standard REST API:

  • Possibility to call a command on a resource (see example below);
  • Possibility to ask for more information when receiving the resources via some request headers, in order to optimize the number of requests you have to do (Ex: Receiving all the children of a document at the same time you receive a document, or receiving all the parents, or all the tasks, ...);
  • Possibility to use various "adapters" that will "transform" the resources that are returned;
  • Possibility to add new endpoints.

Quick Examples

A blog post has been published presenting all the concepts of the Resources endpoints with some nice examples. We provide here some sample ready-to-play cURL requests to try against the Nuxeo demo site (http://demo.nuxeo.com Administrator/Administrator).

  1. Here is how to create a new File document type on the Nuxeo demo instance, right under the default domain (you can copy, paste and test):

  2. You can get the new resource doing a standard GET (actually the JSON object was already returned in previous response):

  3. Now, "lock" this document we have just created by calling an Automation operation from command API on the document resource.

    Pay attention to the Content-Type that is specific when using the @op adapter.

    You can check the result of your request on the web app (http://demo.nuxeo.com/nuxeo/nxpath/default@view_domains, credentials:  Administrator/Administrator).

  4. You can also directly call an automation operation or chain, from the "Command endpoint". Here we return all the worskpaces of the demo.nuxeo.com instance:

Adapters

This API also has the concept of "adapter". An adapter is a URL segment that starts with "@" and that transforms the input resource so as to return another resource. For example, using @blob will return the file of a document (the one stored on the property given by the next URL segment), and chaining it to @op will call an operation (that takes a blob in input):

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:

Files Upload and Batch Processing

The Platform provides facilities for uploading binaries under a given "batch id" on the server, and then to reference that batch id when posting a document resource, or for fetching it from a custom automation chain. 

For instance if you need to create a file with some binary content, first you have to upload the file into the batchManager. It's a place on the system where you can upload temporary files to bind them later.

  1. For that you have to generate yourself a batchId, which will identify the batch : let's say mybatchid.

    Or with curl:

  2. You may verify the content of your batch with the following request.

  3. Next you have to create a document of type File and attach the Blob to it by using the specific syntax on the file:content property.

    Or with curl:

  4. Finally you now can access the content of your file by pointing to the following resource:

Available Client SDKs 

We provide several client SDKs for making it even easier to integrate with the Nuxeo Platform.