Nuxeo API challenges

expose Nuxeo Platform via http without loosing our soul

Being dynamic

• Services to expose depends on deployment option

  +workflowService +conversionService -relationService

• Contribute custom Services

  +myCustomBusinessService

• Data Structures (users, docs ...) depends on configuration

  
  {
  common : {...},
  dublincore : {...},
  customSchema : {...},
  ...
  }
  

Being composable

• "Pack" several services calls inside the same transaction

  updateDoc + validateTask + generatePDF

• Fetch all required information in one call

  • aggregate all required info

  doc attributes + associated tasks + urls

And also

• efficiently manage streams

  byte[]    ==> evil
  MultiPart ==> pain

• manage authentication in an easy and pluggable way

• be HTML/JavaScript friendly

  new XMLHttpRequest()

How we built the Automation API

expose a dynamic http API

JAX-RS vs SOAP

• Soap sucks
  • super static / not composable
  • not web friendly (JS, Blob)
  • heavy and complex
• use JAX-RS + JSON
  • simple but efficient

Automation REST EndPoint

• Expose Nuxeo entities as REST resources
  • Documents, Users, Workflows, Tasks ...

• CRUD via GET, PUT, POST, DELETE

  GET /nuxeo/api/v1/path/{path} HTTP/1.1

  GET /nuxeo/api/v1/id/{uid} HTTP/1.1

  GET /nuxeo/api/v1/user/{userName} HTTP/1.1

  GET /nuxeo/api/v1/group/{groupId} HTTP/1.1

REST Endpoint : GET Document

GET /nuxeo/api/v1/path/default-domain/workspaces/WS/TestNote HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "entity-type": "document",
  "repository": "default",
  "uid": "6a3998e3-6890-45f5-9c19-b708814a9c1c",
  "path": "/default-domain/workspaces/WS/TestNote",
  "type": "Note",
  "state": "project",
  "versionLabel": "0.0",
  "isCheckedOut": true,
  "title": "TestNote",
  "lastModified": "2014-01-20T13:11:29.64Z",
  ...
}

Automation RPC : Operations EndPoint

• Coarse grained API on top of Java API
  • each services can contribute Operations
• Expose endpoint for Operations
  • GET to retrieve definition
  • POST to execute

Operations EndPoint

GET /nuxeo/site/automation/Document.PageProvider HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json


id":"Document.PageProvider",
    "label":"PageProvider",
    "description":"Perform a query ...",
    "signature":[ "void", "documents" ],
    "params":[
      {  "name":"page",
         "type":"integer",
         "required":false
      },{ 

         "name":"query",
         "type":"string",
         "required":false, },
      ... ]
}

Operations EndPoint

POST /nuxeo/site/automation/Document.PageProvider HTTP/1.1
Content-Type: application/json+nxrequest
{ "params" :
    { "query" : "select * from Note",
      "page" : 0
    }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
  "entity-type": "documents",
  "pageIndex": 0,
  "pageSize": 2,
  "pageCount": 2,
  "entries": [
    {
      "entity-type": "document",
      "repository": "default",
      "uid": "3f76a415-ad73-4522-9450-d12af25b7fb4",
      ...
    }, { ...}, ...
 ]
}

Dynamic data structure

Fetch all data in one call

Control Marshaling

• use header to control what schemas should be sent

  X-NXDocumentProperties dublincore, common, file

  fetch the data needed on the client side and nothing more

GET /nuxeo/api/v1/path/default-domain/workspaces/WS/TestNote HTTP/1.1

X-NXDocumentProperties dublincore, common, file

Control Marshaling

HTTP/1.1 200 OK
Content-Type: application/json
{  "entity-type": "document",
  ...
  "properties": {
    "note:mime_type": "text/x-web-markdown",
    "note:note": "##Hello",
    "files:files": [
      {
        "file": {
          "name": "layout.png",
          "mime-type": "image/png",
          "length": "43627",
          "data": "files/6a3998e3-6890-45f5-9c19-b708814a9c1c"
      } } ] } ...
}

Fetch extra info

• use RestContributor to fetch additional info (Mixins)

  • urls, breadcrumb info, comments, related documents ...

• use header to tell server what info is needed

  X-NXContext-Category breadcrumb

GET /nuxeo/api/v1/path/default-domain/workspaces/WS/TestNote HTTP/1.1

X-NXContext-Category breadcrumb

Fetch REST contributions

HTTP/1.1 200 OK
Content-Type: application/json
{
  "entity-type": "document",
  ...
  "contextParameters": {
    "breadcrumb": {
      "entity-type": "documents",
      "entries": [
        {
          "entity-type": "document",
          "repository": "default",
          "path": "/default-domain",
          ...
        }, ... ] } }
}

Leverage adapter system

• contribute custom logic

@WebAdapter(name = BOAdapter.NAME,
            type = "BOService", targetType = "Document")
@Produces({ "application/json+nxentity"})
public class BOAdapter extends DefaultAdapter {

• expose as business object with custom marshaling

GET /nuxeo/api/v1/path/domain/workspaces/WS/note@audit HTTP/1.1

GET /nuxeo/api/v1/path/domain/workspaces/WS/note@bo/MyBO HTTP/1.1

Compose API

Expose the API that matches your needs

Automation Chains

• Operations have Input / Output and Arguments
• Operations can be chained on the service side
  • one call , one transaction

doc => updateDoc
           =(doc)=> validateTask
                            =(doc)=> generatePDF =(Blob)=>

Create new Operations via composition

Compose Chain

via XML / via Drag&Drop

Operations and resources

• Bridge Operations and Resources Endpoints
• "pipe Operation or Chain" on resource

 fetch resource => feed Operation or Chain

POST /nuxeo/api/v1/path/domain/workspaces/WS/note/@op/Blob.ToPDF

Operations and Extensions

• Contribute new Operations via Extension Point
• Contribute new Adapters via Extension Point
• Compose Operations via Workflow

REST EndPoint and Automation

Dynamic and Composable API

Cool, but what is the tradeof

API is more poweful, but more complex

• Data mapping needs to be dynamic

• Calling dynamic endpoints is more complex than static API

endpoint.invoke("createDocument", {input: ... , params:...})

nuxeo.createDocument(path, name, type)

Solution : Provide client lib

• provides some data mapping
• it does some checks
• it provides a simpler API
  (createDocument, addComment ...)

Java, Javascript, Python, Dart, Php ...

SOA and Dynamic API

• More constraints on ESB UI Designer

  • dynamic endpoints and signatures

• Needs dynamic data mapping

  • introspection is required

• Nuxeo complex properties are also a challenge

Mule ESB example

• Leverage Java Lib service wrapper
• Use invoke like pattern for dynamic Operations
  • can not dynamicaly build UI from Automation metadata
• Plug Mule DataSense with Nuxeo Types introspection
  • Mule fetches datatypes from Nuxeo

Dynamic data mapping

Next steps

• nuxeo.io !

• Leverage Automation introspection

  • generate Service wrapper for client libs
  • generate Blockly fragments for UI Chain designer