Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
468 lines (412 sloc) 17.8 KB
title description review labels toc version_override confluence tree_item_index history
Nuxeo API Playground
Nuxeo offers an API Playground, an interactive way to discover the Nuxeo Platform REST API. This module runs fully client-side in JavaScript.
comment date status
2017-12-12
ok
lts2016-ok
howto
rest-api
troger
nuxeo-playground
cors
playground-component
excerpt
multiexcerpt
multiexcerpt-include
lts2017-ok
true
LTS 2015 6.0
710/nxdoc/use-nuxeo-api-playground-to-discover-the-api
60/nxdoc/use-nuxeo-api-playground-to-discover-the-api
ajs-parent-page-id ajs-parent-page-title ajs-space-key ajs-space-name canonical canonical_source page_id shortlink shortlink_source source_link
13664833
REST API
NXDOC
Nuxeo Platform Developer Documentation
Use+Nuxeo+API+Playground+to+Discover+the+API
19793397
9QUuAQ
/display/NXDOC/Use+Nuxeo+API+Playground+to+Discover+the+API
750
author date message version
Solen Guitter
2016-02-16 10:50
53
author date message version
Solen Guitter
2016-02-16 10:10
52
author date message version
Solen Guitter
2016-02-15 17:32
51
author date message version
Solen Guitter
2016-02-15 17:29
50
author date message version
Solen Guitter
2016-02-15 17:27
Resize screenshot
49
author date message version
Solen Guitter
2016-02-15 17:18
48
author date message version
Solen Guitter
2016-02-15 17:17
47
author date message version
Solen Guitter
2016-02-15 17:17
46
author date message version
Solen Guitter
2016-02-15 17:16
45
author date message version
Solen Guitter
2016-02-15 17:16
44
author date message version
Solen Guitter
2016-02-15 17:16
43
author date message version
Solen Guitter
2016-02-15 17:16
42
author date message version
Solen Guitter
2016-02-15 17:15
41
author date message version
Solen Guitter
2016-02-15 17:15
40
author date message version
Solen Guitter
2016-02-15 17:14
39
author date message version
Solen Guitter
2016-02-15 17:14
38
author date message version
Solen Guitter
2016-02-15 17:13
37
author date message version
Solen Guitter
2016-02-15 17:13
36
author date message version
Solen Guitter
2016-02-15 17:12
35
author date message version
Solen Guitter
2016-02-15 17:12
34
author date message version
Solen Guitter
2016-02-15 17:11
Move allowClientGeneratedBatchId setup to configuration section, review command endpoint and batch upload sections
33
author date message version
Solen Guitter
2016-02-15 14:30
32
author date message version
Nelson Silva
2015-12-07 17:45
Add link to marketplace package
31
author date message version
Nelson Silva
2015-12-07 17:07
30
author date message version
Nelson Silva
2015-12-07 16:46
29
author date message version
Nelson Silva
2015-12-07 16:43
Added Batch Upload documentation
28
author date message version
Nelson Silva
2015-12-07 16:13
Update according to repository browser changes
27
author date message version
Thibaud Arguillere
2015-10-23 21:15
26
author date message version
Solen Guitter
2014-09-08 18:35
25
author date message version
Solen Guitter
2014-09-02 16:09
24
author date message version
Solen Guitter
2014-09-02 16:09
23
author date message version
Solen Guitter
2014-09-02 15:48
22
author date message version
Solen Guitter
2014-09-02 15:48
21
author date message version
Solen Guitter
2014-09-02 15:47
20
author date message version
Solen Guitter
2014-09-02 15:47
19
author date message version
Solen Guitter
2014-09-02 15:45
18
author date message version
Solen Guitter
2014-09-02 15:44
17
author date message version
Solen Guitter
2014-09-02 15:44
16
author date message version
Solen Guitter
2014-09-02 15:43
15
author date message version
Solen Guitter
2014-09-02 15:42
14
author date message version
Solen Guitter
2014-09-02 15:41
13
author date message version
Solen Guitter
2014-09-02 15:36
12
author date message version
Solen Guitter
2014-09-02 12:08
11
author date message version
Solen Guitter
2014-09-02 12:06
10
author date message version
Alain Escaffre
2014-07-03 02:35
9
author date message version
Alain Escaffre
2014-07-03 02:33
8
author date message version
Alain Escaffre
2014-07-03 02:33
7
author date message version
Alain Escaffre
2014-07-03 02:27
6
author date message version
Alain Escaffre
2014-07-03 02:23
5
author date message version
Alain Escaffre
2014-07-03 02:22
4
author date message version
Alain Escaffre
2014-07-03 02:12
3
author date message version
Alain Escaffre
2014-07-03 01:57
2
author date message version
Alain Escaffre
2014-07-03 01:53
1

{{! excerpt}} Nuxeo offers an API Playground, an interactive way to discover the Nuxeo Platform REST API. This module runs fully client-side in JavaScript. You can use it on any server as long as you deploy a CORS configuration on it. {{! /excerpt}}

Functional Overview

Nuxeo API Playground can be used online 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 of API Playground connects to our https://demo.nuxeo.com instance by default, but you can use it with your own Nuxeo server.

![]({{file name='playground_server_login_box.png'}} ?w=500,border=true)

Repository

Playing with the API will modify the content of the repository. The Repository section of the playground will let you verify the impact of your API call attempts.

![]({{file name='playground_repository_section.png'}} ?w=300,h=120,border=true)

The content is represented in a tree structure which allows you to navigate the repository. Unfold the tree and click on a document. Its content is retrieved through REST API with JSON responses and headers displayed in the right panel. ![]({{file name='playground_repository_document.png'}} ?w=500,h=421,border=true) The left side panel allows you to explore the [REST API endpoints]({{page page='rest-api-endpoints'}}) available for the selected document. The tabs allow you to switch between HTTP methods (GET, PUT, POST and DELETE) enabling you to read, update, create and delete documents.

![]({{file name='playground_repository_PUT_tab.png'}} ?w=300,h=294,border=true)

The default GET tab allows you to invoke [adapters]({{page page='rest-api-web-adapters'}}) on the current document as well as toggle [content enrichers]({{page page='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 displays a form where you can enter the parameters, if any. ![]({{file name='playground_repository_GET_tab.png'}} ?w=400,border=true)

Data Structure

We use the API to create/read/update documents. But to do so, you need to know which properties are expected for your document. The Data Structures section helps you understand this by listing all the document types, facets and schemas that have been configured on your Nuxeo Platform repository.

![]({{file name='playground_data_structures_section..png'}} ?w=300,h=116,border=true)

For example, to get information about the userWorkspaceRoot document:

  1. In Types, click on the userWorkspaceRoot document type. ![]({{file name='playground_document_type_properties.png'}} ?w=300,border=true,thumbnail=true) The schemas and facets of the document are displayed.
  2. Click on the icon ![]({{file name='playground_sitemap_icon.png'}}). The complete inheritance structure of userWorkspaceRoot is displayed. ![]({{file name='playground_inheritance_structure.png'}} ?w=500,border=true)
  3. Click on one of the schema names, like dublincore for instance, to see its structure. ![]({{file name='playground_schema_structure.png'}} ?w=500,border=true)

{{> anchor 'resources-endpoints'}}Resources Endpoints

In this section you can perform calls to all the [Resources Endpoints]({{page page='rest-api-endpoints#resources-endpoints'}}).

![]({{file name='playground_resources_endpoints_section.png'}} ?w=300,h=111,border=true)

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 with and then on the call you want to make.

  2. Fill in the Parameters form.

    Tips:

    • For [Document Resources]({{page page='document-resources-endpoints'}}), you can select the document in the repository tree by clicking on the icon ![]({{file name='playground_browse_icon.png'}}), without having to type in its exact ID.
    • For all the resources, when you perform a PUT request (usually to update the resource), you can click on the Fetch Document button to automatically fill in the body parameter of your request with the document JSON definition. Then you just need to modify the property you want to update. ![]({{file name='playground_fetch_document_PUT.png'}} ?w=300,h=163,border=true)
    • When you perform 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 up. ![]({{file name='playground_fetch_document_POST.png'}} ?w=500,border=true)
  3. Optionally click on the icon ![]({{file name='playground_settings_icon.png'}}) to update the [request headers]({{page page='special-http-headers'}}) before running the call.

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

    {{! multiexcerpt name='response-headers-curls-tabs'}}

    • The Response content, most of the time a JSON string, but sometimes the returned error, or a byte stream if the answer was a binary. ![]({{file name='playground_response_tab.png'}} ?w=500,h=256,border=true)
    • The headers both of the request and the response: ![]({{file name='playground_headers_tab.png'}} ?w=500,h=290,border=true)
    • The CURL syntax of the request This tab is key as it allows you to reproduce the same call in your own environment/shell to ensure you're not missing anything to build a successful request. ![]({{file name='playground_curl_requests_tab.png'}} ?w=500,border=true){{! /multiexcerpt}}

{{> anchor 'command-endpoint'}}Command Endpoint

The command endpoint section lists all the available [operations and chain of operations]({{page page='automation'}}) available on the server. You can then run an operation by filling in the expected input (nothing, documents or binaries) and then get the output.

  1. Click on the operation category and then on the operation you want to run.

  2. Fill in the operation parameters form. See [Operation Parameters documentation]({{page page='content-automation-concepts#operation-parameters'}}) or the list of Operations on Nuxeo Explorer for more information on the parameters.

    Tip: For document input, click on the icon ![]({{file name='playground_browse_icon.png'}}) to browse the repository tree and select your document instead of typing the whole document path.

  3. Optionally click on the icon ![]({{file name='playground_settings_icon.png'}}) to update the [request headers]({{page page='special-http-headers'}}) before running the call.

  4. Click on the Run button. You get three tabs: {{{multiexcerpt 'response-headers-curls-tabs' page='howto-nuxeo-api-playground'}}}

Batch Upload

The [Batch Upload Endpoint]({{page page='batch-upload-endpoint'}}) provides a way of uploading one or more files and then referencing that set of files from the API (PUT and POST calls, operation parameters, etc.). This approach is favored over regular HTTP MultiPart encoding uploads 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

![]({{file name='playground_batch_upload.png'}} ?w=500,h=325,border=true)

Pre-Requisites

Because the Nuxeo API Playground currently uses the old API, you need to do some configuration to enable it. 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.

![]({{file name='playground_batch_upload_batch_uploaded.png'}} ?w=500,h=84,border=true)

Using a Batch Upload

  1. Click on the Reference a Batch button which is displayed for any JSON document parameter. ![]({{file name='playground_batch_upload_batch_selection.png'}} ?w=500,h=426,border=true) A dialog containing the required file:content value is displayed. ![]({{file name='playground_batch_upload_JSON_definition.png'}} ?w=500,h=339,border=true)
  2. Copy the relevant part of the JSON definition in the form. ![]({{file name='playground_batch_upload_JSON_pasted.png'}} ?w=500,h=496,border=true)
  3. Click on the Run button.

{{> anchor 'install-config'}}Installation and Configuration

Installing Nuxeo Playground

{{{multiexcerpt 'MP-installation-easy' page='Generic Multi-Excerpts'}}}

After you've installed the Nuxeo Package, go to http://NUXEO_SERVER/nuxeo/playground to use the API Playground. It suggests that you 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).

{{> anchor 'enable-batch-upload'}}Enabling Batch Upload

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

To enable Batch upload set the runtime configuration property allowClientGeneratedBatchId to "true", [using an XML extension]({{page page='how-to-contribute-to-an-extension'}}).

{{#> panel type='code' heading='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>

{{/panel}}

{{> anchor 'setting-up-cors-configuration'}}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 name='cors-config.xml'}}) file that works as long as you put it in the NUXEO_HOME/nxserver/config folder. Read the [CORS documentation]({{page page='cross-origin-resource-sharing-cors'}}) for more details.


{{#> panel heading='Related Documentation'}}
  • [Special HTTP Headers]({{page page='special-http-headers'}})
  • [Automation]({{page page='automation'}})
  • [Document Resources Endpoints]({{page page='document-resources-endpoints'}})
  • [REST API]({{page page='rest-api'}})

{{/panel}}

 

You can’t perform that action at this time.