REST API

Web Adapters for the REST API

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


 
4 months ago manonlumeau Relocated assets to fit new URL structure for 710 - fix
3 years ago Bertrand Chauvin 21
3 years ago Bertrand Chauvin 20
3 years ago Bertrand Chauvin 19
3 years ago Damien Metzler 18
4 years ago Manon Lumeau 17 | Fix links to 7.10
4 years ago Arnaud Kervern 16
4 years ago Manon Lumeau 15
4 years ago Solen Guitter 13 | Add examples from page Document Resources Endpoints
4 years ago Solen Guitter 14
4 years ago Solen Guitter 12 | Add task and workflow web adapters
4 years ago Solen Guitter 11 | page formatting
4 years ago Solen Guitter 10
4 years ago Solen Guitter 9 | Add convert, rendition and search web adapters and related documentation
4 years ago Solen Guitter 8
4 years ago Solen Guitter 7
4 years ago Thierry Delprat 6
4 years ago Thierry Delprat 5
4 years ago Thierry Delprat 4
4 years ago Thierry Delprat 3
4 years ago Thierry Delprat 2
5 years ago Alain Escaffre 1
History: Created by Alain Escaffre

We'd love to hear your thoughts!

All fields required