Home > Developer Documentation Center > REST API > Use Nuxeo API Playground to Discover the API
REST API

Use Nuxeo API Playground to Discover the API

Updated: July 17, 2023

We made an API Playground available that offers an interactive way to discover the Nuxeo Platform API. This module runs fully client side in JavaScript, and makes use of the API of Nuxeo Platform it targets. You can use it on any server as long as you deploy a CORS configuration on it.

Functional Overview

Nuxeo API Playground can be used online at http://nuxeo.github.io/api-playground/ or locally at http://NUXEO_SERVER/nuxeo/playground after you install the Nuxeo Package on your server (see the Installation and Configuration section).

Note that the online version proposes to connect the API Playground to our demo.nuxeo.com instance by default, but you can use it with your own Nuxeo server.

Repository

As you play with the APIs, you will modify the content of the repository. The Repository section of the playground will let you check the impact of your API call attempts.

The content is represented as a tree which allows you to navigate the repository. Unfold the tree and click on a document. Its content is retrieved through the REST API with the JSON response and headers displayed on the right panel.

The left side panel allows you to explore the REST endpoints available for the selected document (see also the . The tabs allow you to switch between HTTP methods (GET, PUT, POST and DELETE) thus enabling you to read, update, create and delete documents.

The default GET tab allows you to invoke adapters on the current document as well as toggle content enrichers. By default the thumbnail and breadcrumb enrichers are selected since they are used to build the header where this information is shown. Selecting an adapter shows a form with its parameters, if any.

Data Structure

One of the main cases of using the API is to create/read/update documents. For doing so, you need to know what properties are expected for your document. The Data Structures section helps you understand it, by listing all the document types, facets and schemas that have been configured on your Nuxeo Platform repository.

For instance, to get information about the userWorkspaceRoot document type:

  1. In Types, click on the userWorkspaceRoot document type.
    The schemas and facets of the document are displayed.
  2. Click on the icon . The complete inheritance structure of userWorkspaceRoot is displayed.
  3. Click on one of the schema names, like dublincore for instance, to see its structure.

Resources Endpoints

In this section you can perform calls to all the "Resources" endpoints.

Depending on the endpoint, you can do GET, PUT, POST or DELETE calls to read, update, create and delete documents.

  1. Click on the resource endpoint you want to work on and then on the call you want to make.
  2. Fill in the Parameters form. Tips:
    • For Resources of type document, you can select the document in the repository tree by clicking on the icon , without having to type its exact id.
    • For all the resources, when you want to do a PUT (most of the time to update the resource), you can click on the Fetch document button to prefill the body parameter of your request with the document JSON definition. Then you just need to modify the property you want to update.
    • When you are doing a POST call and need an example of the expected JSON object, click on the value displayed in the Type column. The documentation of the corresponding JSON structure opens.
  3. Optionally click on the icon
    to update the request headers before running the call.

  4. Click on the Run button. You get three tabs:

    • The Response content, most of the time a JSON string, but sometimes the returned error, or a bite stream if the answer was a binary.
    • The headers both of the request and the response:
    • The CURL syntax of the request This tab is a key one as it allows you to reproduce the same call on your own environment/shell so as to make sure you didn't miss anything for building a successful request.

Command Endpoint

The command endpoint section lists all the available operations and chain of operations available on the server. You can then run an operation by filling the expected input (nothing, documents or binaries) and then get the output.

  1. Click on operation category and then on the operation you want to run.
  2. Fill in the operation parameters form. See the Operation parameters documentation or operations list on the Explorer for more information on the parameters. Tip: For document input, click on the icon to browse the repository tree and find your document, instead of typing the document path.
  3. Optionally click on the icon
    to update the request headers before running the call.

  4. Click on the Run button. You get three tabs:

    • The Response content, most of the time a JSON string, but sometimes the returned error, or a bite stream if the answer was a binary.
    • The headers both of the request and the response:
    • The CURL syntax of the request This tab is a key one as it allows you to reproduce the same call on your own environment/shell so as to make sure you didn't miss anything for building a successful request.

Batch Upload

The Batch Upload endpoint provides a way to upload one or more files and then reference that set of files from the API (PUT and POST calls, operation parameters, etc.). This approach is favored over regular HTTP MultiPart encoding upload in the following cases:

  • When you have several files to upload

  • When your client does not natively support multipart encoding

  • When you want to upload files as soon as possible and then run the operation when everything has been uploaded on the server

Pre-Requisites

Because the Nuxeo API Playground currently uses the old API, you need to some configuration to enable. See the section Enabling Batch Upload.

Creating a Batch Upload

  1. Select one or more files to upload.
  2. Click the Upload button. Once your files are uploaded the batch will be displayed in the list of batches. You can create any number of batches before referencing them in your requests.

Using a Batch Upload

  1. Click on the Reference a batch button which is displayed for any JSON document parameter.
    A dialog containing the required file:content value is displayed.
  2. Copy the relevant part of the JSON definition in the form.
  3. Click on the Run button.

Installation and Configuration

Installing Nuxeo Playground

This addon requires no specific installation steps. It can be installed like any other package from the Update Center or using nuxeoctl command line.

After you installed the Nuxeo Package, go to http://NUXEO_SERVER/nuxeo/playground to use the API Playground. Note that it suggest to log in to the public website demo.nuxeo.com by default. Make sure you change the URL to use your server's (http://NUXEO_SERVER/nuxeo by default).

Enabling Batch Upload

Batch Upload on the API Playground currently uses the old API which is currently deprecated but kept for backward compatibility. It also relies on client side generated batch ids which must to be enabled so the upload from the API Playground UI works.

To enable Batch upload set the runtime configuration property allowClientGeneratedBatchId to "true", using an XML extension.

nxserver/config/batch-upload-config.xml

<component name="org.nuxeo.ecm.automation.server.BatchManager.configuration.test">
  <extension target="org.nuxeo.runtime.ConfigurationService" point="configuration">
    <property name="allowClientGeneratedBatchId">true</property>
  </extension>
</component>

Setting up a CORS Configuration

If your Nuxeo server and the API Playground are not in the same domain, you need to set up a CORS configuration. We provide a sample configuration file that works as long as you put it in the NUXEO_HOME/nxserver/config folder. Read the CORS documentation for more details.

Related Documentation