Home > Developer Documentation Center > REST API > Web Adapters for the REST API
REST API

Web Adapters for the REST API

Updated: July 17, 2023

Adapters and REST Resources 

WebEngine, the JAX-RS Server used to serve the REST API, has the concept of WebAdapter for DocumentModel. Logically the REST API leverages this concept to expose adapters on top of the Document REST end point.

An adapter is a URL segment that starts with @ and that 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:

/nuxeo/api/v1/id/{docId}/@adapter/parameters

/nuxeo/api/v1/path/{documentPath}/@adapter/parameters

The notion of Adapter precedes the concept of Content Enricher. In some cases, some of the adapters presented here could be replaced by Content Enrichers.

Simple Document Adapters

Several default adapters are provided by default.

acl

  • Usage: Returns the ACLs of the target Document.

  • Sample URL:

    /nuxeo/api/v1/id/{docId}/@acl

audit

  • Usage: Returns audit trails records corresponding to the target Document.

  • Sample URL:

    /nuxeo/api/v1/id/{docId}/@audit

blob

  • Usage: Returns the Blob corresponding to the Document attribute matching the XPath parameter.

  • Sample URL:

    /nuxeo/api/v1/id/{docId}/@blob/{xpath}

children

  • Usage: Returns children of the target Document. Query parameters are not mandatory and are by default:

    • page: 0
    • pageSize: 50
    • maxResult: nolimit

  • Sample URL:

    /nuxeo/api/v1/id/{docId}/@children

convert

  • Usage: Returns the conversion of a blob. Query parameters, you must use one of them:
    • converter
    • type
    • format

  • Sample URL:

    /nuxeo/api/v1/id/{docId}/@convert?format=pdf

pp

  • Usage: Returns the result of the query corresponding to the named PageProvider. The target Document is used to provide the parameters of the PageProvider (i.e. SearchDocumentModel).

  • Sample URL:

    /nuxeo/api/v1/id/{docId}/@pp/{pageProviderName}

rendition

  • Usage: Returns the renditions of a blob.

  • Sample URL:

    /nuxeo/api/v1/id/{docId}/@rendition/{renditionName}

search

  • Usage: Returns paged results of the query. Query can be a full-text query or a NXQL query. Query parameters are not mandatory and are by default:
    • orderBy: dc:title
    • page: 0
    • pageSize: 50
    • maxResult: nolimit

  • Sample URL:

    /nuxeo/site/api/v1/path/{docId}/@search?fullText=nuxeo&orderBy=dc:title

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

task

  • Usage: Returns task instance you have permission to see.

  • Sample URL:

    /nuxeo/api/v1/id/{docId}/@task

workflow

  • Usage: Returns workflow instances launched by current user.

  • Sample URL:

    /nuxeo/api/v1/id/{docId}/@workflow

Getting the Children of a Given Document - @children

Example

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

Response

{
    "entity-type": "documents",
    "isPaginable": true,
    "totalSize": 3,
    "pageIndex": 0,
    "pageSize": 50,
    "pageCount": 1,
    "entries": [
      {   
        "entity-type": "document",
        "repository": "default",
        "uid": "afb373f1-08ed-4228-bfe8-9f93131f8c84",
        "path": "/default-domain/sections",
        "type": "SectionRoot",
            ...
        "contextParameters": {
            "documentURL": "/nuxeo/site/api/v1/id/afb373f1-08ed-4228-bfe8-9f93131f8c84"
        }            
       },
       ...
    ]
}

In the response, for each document, you have a documentURL property that points to the API endpoint's id.

Full-Text Search

GET /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 /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"
            ]
        }
    ]
}

Custom Adapters

You can of course contribute new WebAdapters using WebEngine.

An other alternative is to use the @bo WebAdapter to leverage standard Nuxeo DocumentModelAdapters that can be defined using the adapter extension point.

/nuxeo/api/v1/id/{docId}/@bo/{documentAdapterName}

Getting a Business Object

GET Request Body

GET /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, you just have to send a PUT request one the business object resource with its content data like this:

PUT Request Body

PUT /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

And then to create a business object, you have to issue a POST on the object resource plus the name of the newly created document, like this:

POST Request Body

POST /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

The @op adapter can be used to pipe the identified Document as input of an operation.

Sample URL

/nuxeo/api/v1/id/{docId}/@op/{OperationName}

Sample POST Request Body

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

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

You can also use it to run a chain by prefixing the chain name by Chain. , for instance:

Sample URL

/nuxeo/site/api/v1/path/{pathOfTheDoc}/@op/Chain.{myChain}

Sample POST Request Body on a Document

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

Sample POST Request Body on a List of Documents

POST /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 document of the current page.

Piping

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

Here is an example :

Sample URL

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

Related Documentation