REST API Web Adapters

Adapters and REST Resources

WebEngine, the JAX-RS Server used to serve the REST API, offers WebAdapters for the Document Model. The REST API leverages this concept to expose adapters on top of the Document REST endpoint.

A WebAdapter is a URL segment starting with @ which transforms the input resource so as to return another resource. The idea is to have a URL pointing to a Document and use the adapter to convert the Document into something else before the result is returned. The general syntax is:

http://NUXEO_SERVER/nuxeo/api/v1/id/{docId}/@adapter/{parameters}

http://NUXEO_SERVER/nuxeo/api/v1/path/{documentPath}/@adapter/{parameters}

The notion of adapter precedes the concept of Content Enricher. Some of the adapters presented here could be replaced by Content Enrichers.

Simple Document Adapters

Default adapters provided by default.

Adapter	Usage and sample URL
@acl	Returns the ACLs of the target Document
	`/api/v1/id/{docId}/@acl`

@annotation	Returns annotations corresponding to the target Document and file:content blob
	`/api/v1/id/{docId}/@annotation`

@audit	Returns audit trail records corresponding to the target Document
	`/api/v1/id/{docId}/@audit`

@blob	Returns the Blob corresponding to the Document attribute matching the XPath parameter
	`/api/v1/id/{docId}/@blob/{xpath}`

@children	Returns children of the target Document Query parameters (optional) are by default: `page:0` `pageSize:50` `maxResult:nolimit`
	`/api/v1/id/{docId}/@children`

@comment	Returns comments corresponding to the target Document
	`/api/v1/id/{docId}/@comment`

@convert	Returns the conversion of a blob Query parameters (must use one): `converter` `type` `format`
	`/api/v1/id/{docId}/@convert?format=pdf`

@emptyWithDefault Returns an empty document initialized with default properties.
The target document acts as the parent of the empty document.
Query parameters:
type: required, type of the empty document.
name: optional, name of the empty document.

Note that calling emptyWithDefault adapter triggers the emptyDocumentModelCreated core event, so the returned empty document will have all properties set by listeners listening to emptyDocumentModelCreated as well.

/api/v1/id/{docId}/@emptyWithDefault?type=File&name=test

@pp	Returns the result of the query corresponding to the named PageProvider. The target Document is used to provide the parameters of the PageProvider (SearchDocumentModel).
	`/api/v1/id/{docId}/@pp/{pageProviderName}`

@rendition	Returns the renditions of a blob
	`/api/v1/id/{docId}/@rendition/{renditionName}`

@search	Returns paged results of the query (full-text or NXQL) Query parameters (optional) are by default: `orderBy:dc:title` `page:0` `pageSize:50` `maxResult:nolimit`
	`/api/v1/path/{docId}/@search?fullText=nuxeo&orderBy=dc:title` `/api/v1/path/{pathOfTheDoc}/@search?query=SELECT * FROM File`

@task	Returns the task instance you have permission to see
	`/api/v1/id/{docId}/@task`

@workflow	Returns workflow instances launched by current user
	`/api/v1/id/{docId}/@workflow`

Group Adapters

Default adapters provided by default.

@users	Returns the member users of a group
	`/api/v1/group/{groupId}/@users`

@groups	Returns the member groups of a group
	`/api/v1/group/{groupId}/@groups`

Custom Adapters

You can contribute new WebAdapters using WebEngine.

Alternatively, use the @bo WebAdapter to leverage standard Nuxeo DocumentModelAdapters which you can define with the adapter extension point.

@bo	Specify the custom adapter you wish to use
	`/api/v1/id/{docId}/@bo/{documentAdapterName}`

Or use the @op adapter to access operations.

@op	Pipe document as input for an operation or automation chain
	`/api/v1/id/{docId}/@op/{OperationName}` `/api/v1/path/{pathOfTheDoc}/@op/Chain.{myChain}`

Piping

Adapters can be chained: the result of one adapter becomes the input of the next one.

Here is an example :

Sample URL

/api/v1/id/{docId}/@blob/file:content/@op/Blob.ToPDF

Examples

Getting the Children of a Given Document - `@children`

Example

GET http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@children?currentPageIndex=0&pagesize=20&maxResults=100

Response

{
  "entity-type": "documents",
  "isPaginable": true,
  "resultsCount": 1,
  "pageSize": 50,
  "maxPageSize": 1000,
  "currentPageSize": 1,
  "currentPageIndex": 0,
  "numberOfPages": 1,
  "isPreviousPageAvailable": false,
  "isNextPageAvailable": false,
  "isLastPageAvailable": false,
  "isSortable": true,
  "hasError": false,
  "errorMessage": null,
  "totalSize": 1,
  "pageIndex": 0,
  "pageCount": 1,
  "entries": [{
    "entity-type": "document",
    "repository": "default",
    "uid": "0178eb31-b1ca-49af-86b0-ff59d671dc91",
    "path": "/default-domain",
    "type": "Domain",
    "state": "project",
    "parentRef": "6db16630-9e06-42ba-8ce2-e5a0f14e9ee7",
    "isCheckedOut": true,
    "isVersion": false,
    "isProxy": false,
    "changeToken": "1481174085000",
    "title": "Domain",
    "lastModified": "2016-12-08T05:14:45.00Z",
    "facets": ["Folderish", "SuperSpace", "NotCollectionMember"]
  }]
}

Searching Documents - `@search`

Full-Text Search

GET http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@search?fullText=nuxeo&orderBy=dc:title

Response Example

{
  "entity-type": "documents",
  "isPaginable": true,
  "resultsCount": 2,
  "pageSize": 50,
  "maxPageSize": 0,
  "currentPageSize": 2,
  "currentPageIndex": 0,
  "numberOfPages": 1,
  "isPreviousPageAvailable": false,
  "isNextPageAvailable": false,
  "isLastPageAvailable": false,
  "isSortable": true,
  "hasError": false,
  "errorMessage": null,
  "totalSize": 2,
  "pageIndex": 0,
  "pageCount": 1,
  "entries": [{
    "entity-type": "document",
    "repository": "default",
    "uid": "7808880b-9a2d-4f91-89d8-1bc49f6ba526",
    "path": "/default-domain/templates/customerReferenceDOCX",
    "type": "TemplateSource",
    "state": "project",
    "parentRef": "6ef6675e-4ec8-4484-88f6-62651c7311ad",
    "isCheckedOut": true,
    "changeToken": "1430295774263",
    "title": "Customer reference using Word template",
    "lastModified": "2015-04-29T08:22:54.26Z",
    "facets": [
      "Versionable",
      "Commentable",
      "HasRelatedText",
      "Thumbnail",
      "Downloadable",
      "Template"
    ]
  }, {
    "entity-type": "document",
    "repository": "default",
    "uid": "fd63af66-07d4-4430-8b13-f17c25d2513a",
    "path": "/default-domain/templates/interventionStatement",
    "type": "TemplateSource",
    "state": "project",
    "parentRef": "6ef6675e-4ec8-4484-88f6-62651c7311ad",
    "isCheckedOut": true,
    "changeToken": "1430295774052",
    "title": "Delivery Statement",
    "lastModified": "2015-04-29T08:22:54.05Z",
    "facets": [
      "Versionable",
      "Commentable",
      "HasRelatedText",
      "Thumbnail",
      "Downloadable",
      "Template"
    ]
  }]
}

If the pointed resource is not a Folder, then the search is issued from the parent document.

NXQL Search

You can also make some direct NXQL queries with this endpoint, like this:

GET Request Body

GET http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@search?query=SELECT * FROM File

Response Example

{
  "entity-type": "documents",
  "isPaginable": true,
  "resultsCount": 4,
  "pageSize": 50,
  "maxPageSize": 0,
  "currentPageSize": 4,
  "currentPageIndex": 0,
  "numberOfPages": 1,
  "isPreviousPageAvailable": false,
  "isNextPageAvailable": false,
  "isLastPageAvailable": false,
  "isSortable": true,
  "hasError": false,
  "errorMessage": null,
  "totalSize": 4,
  "pageIndex": 0,
  "pageCount": 1,
  "entries": [{
    "entity-type": "document",
    "repository": "default",
    "uid": "38723e10-80f8-477d-bb5e-6dcd9cf76f9f",
    "path": "/default-domain/workspaces/templatesamples/intervention",
    "type": "InterventionStatement",
    "state": "project",
    "parentRef": "a05f7f31-6727-48db-b8d9-a89023135867",
    "isCheckedOut": true,
    "changeToken": "1430295774082",
    "title": "Sample Intervention Statement",
    "lastModified": "2015-04-29T08:22:54.08Z",
    "facets": [
      "Versionable",
      "Publishable",
      "Commentable",
      "TemplateBased",
      "HasRelatedText",
      "Downloadable"
    ]
  }, {
    "entity-type": "document",
    "repository": "default",
    "uid": "489819bd-f265-47a6-931a-236cd55f97ec",
    "path": "/default-domain/workspaces/templatesamples/spec",
    "type": "File",
    "state": "project",
    "parentRef": "a05f7f31-6727-48db-b8d9-a89023135867",
    "isCheckedOut": true,
    "changeToken": "1430295774195",
    "title": "Spec",
    "lastModified": "2015-04-29T08:22:54.19Z",
    "facets": [
      "Versionable",
      "Publishable",
      "Commentable",
      "TemplateBased",
      "HasRelatedText",
      "Thumbnail",
      "Downloadable"
    ]
  }]
}

Getting Annotations - `@annotation`

Create annotation

POST http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@annotation
{
  "entity-type": "annotation",
  "id": "ID",
  "documentId": "DOC_ID",
  "xpath": "file:content",
  "entity": "ENTITY"
}

Get annotation

GET http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@annotation/{annotationId}

Get annotations

GET http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@annotation?xpath=file:content

Update annotation

PUT http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@annotation
{
  "entity-type": "annotation",
  "entity": "ENTITY"
}

Delete annotation

DELETE http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@annotation/{annotationId}

Getting a Business Object

GET Request Body

GET http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@bo/BusinessBeanAdapter

Response

{
  "entity-type": "BusinessBeanAdapter",
  "id": "37b1502b-26ff-430f-9f20-4bd0d803191e",
  "type": "Domain",
  "title": "Default domain",
  "description": ""
}

Updating a Business Object

To update a business object, send a PUT request on the business object resource with its content data:

PUT Request Body

PUT http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@bo/BusinessBeanAdapter
{
  "entity-type": "BusinessBeanAdapter",
  "value": {
    "id": "37b1502b-26ff-430f-9f20-4bd0d803191e",
    "type": "Domain",
    "title": "Default domain",
    "description": "My new description"
  }
}

Creating a Business Object

To create a business object, issue a POST on the object resource with the name of the newly created document:

POST Request Body

POST http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@bo/BusinessBeanAdapter/{newName}
{
  "entity-type": "BusinessBeanAdapter",
  "value": {
    "type": "Note",
    "title": "A sample note",
    "description": "",
    "note": "The content of my note",
  }
}

Bridging Operations and Automation Chains

Sample POST Request Body

POST http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@op/{myOperation}
{
  "params": {
    "opParam": "value"
  }
}

The response will depend on the result of the automation chain.

Sample POST Request Body on a Document

POST http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@op/Chain.{myChain}
{
  "params": {
    "chainParam": "value"
  }
}

Sample POST Request Body on a List of Documents

POST http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheFolder}/@children/@op/Chain.myChain
{
  "params": {
    "chainParam": "value"
  }
}

Pay attention to the fact that document list adapters are paged. That means that the chain will run on all documents of the current page.

Contributing A Web Adapter

Not completely satisfied with what's on offer? See how to contribute a web adapter!

REST API Web Adapters

Adapters and REST Resources

Simple Document Adapters

Group Adapters

Custom Adapters

Piping

Examples

Getting the Children of a Given Document - @children

Searching Documents - @search

Getting Annotations - @annotation

Getting a Business Object

Updating a Business Object

Creating a Business Object

Bridging Operations and Automation Chains

Contributing A Web Adapter

Getting the Children of a Given Document - `@children`

Searching Documents - `@search`

Getting Annotations - `@annotation`