How to Extend the Nuxeo REST API


Tue 28 April 2015 By Guillaume Renard

The Nuxeo REST API has been designed to be highly pluggable giving us the flexibility to add new modules whenever required. This means you can extend the Nuxeo REST API to contribute new endpoints without breaking a sweat! Here I will share the technical details about the implementation and also show how to extend the REST API using a simple workflow example.

How the Nuxeo REST API Contributes Endpoints


The Nuxeo REST API is coded in the nuxeo-rest-api-server module. It is a WebEngine module which:


  • defines an APIRoot.java, the resource class serving request for /nuxeo/api/v1 through the javax.ws.rs.Path annotation:
    @Path("/api/v1{repo : (/repo/[^/]+?)?}")


  • provides these resources as WebObjects.

  • allows the Writers and Readers to serialize and unserialize these resources.


As an example, let’s have a look at the directory endpoint and see how it resolves a GET on /nuxeo/api/v1/directory/continent/africa.

First, APIRoot.java retrieves the proper directory WebObject with:

@Path("/directory")
public Object doGetDirectory() {
return newObject("directory");
}

The directory WebObject is made available by DirectoryRootObject.java:

@WebObject(type = "directory")
public class DirectoryRootObject extends DefaultObject {
@Path("{directoryName}")
public Object doGetDirectory(@PathParam("directoryName") String dirName){
return newObject("directoryObject", dirName);
}
}

This will resolve the directoryName continent passed as a path parameter and serve the DirectoryObject.java.

@Path("{entryId}")
public Object getEntry(@PathParam("entryId") final String entryId) {
return withDirectorySession(directory, new DirectorySessionRunner<Object>()) {
@Override
Object run(Session session) throws ClientException {
DocumentModel entry = session.getEntry(entryId);
if (entry == null) {
throw new WebResourceNotFoundException("Entry not found");
}
return newObject("directoryEntry", new DirectoryEntry(directory.getName(), entry));
}
});
}

This DirectoryObject.java then resolves the africa directory entry to serve the DirectoryEntryObject.java which will finally return a DirectoryEntry.java entity:
@GET
public DirectoryEntry doGet() {
return entry;
}

Last but not the least, this DirectoryEntry entity has to be serialized and unserialized in JSON. This can be respectively done by:

Extend the REST API: The Workflow Example


Starting from the Nuxeo Platform 7.2, we have added new REST endpoints to initiate and run workflows. The new endpoints documentation is available on the api-playground:


  • workflow endpoint

  • workflowModel endpoint

  • task endpoint


This a good example of how to contribute a new set of endpoints. One interesting point was extending the existing Nuxeo REST API module from another bundle in order to make new endpoints available under the existing /nuxeo/api/v1 resource path.

This is now possible, thanks to OSGI fragment. As defined in OSGI documentation:

A Bundle fragment, or simply a fragment, is a bundle whose contents are made available to another bundle (the fragment host).

In case of the Nuxeo workflow REST API, we introduced a new bundle called nuxeo-routing-rest-api which is a fragment of the host rest-api bundle. To achieve this, we simply need to:


  • Declare the Fragment-Host in the MANIFEST.MF of the fragment bundle as follow:




Manifest-Version: 1.0
Bundle-ManifestVersion: 1
Bundle-Name: nuxeo-routing-rest-api
Bundle-SymbolicName: org.nuxeo.ecm.platform.restapi.server.routing;singleton:=true
Fragment-Host: org.nuxeo.ecm.platform.restapi.server
Bundle-Vendor: Nuxeo
Bundle-Version: 1.0.0


In case of the workflow REST API, all webObjects and entity readers/writers are grouped within the org.nuxeo.ecm.restapi.server.jaxrs.routing package.

As a direct result and thanks to a routing method introduced in the Nuxeo Platform 7.2, all webObjects located in the fragment bundle of the rest-api bundle will be discovered and made available on the /nuxeo/api/v1 resource path as well as to their readers and writers. For instance, WorkflowObject.java from the nuxeo-routing-rest-api fragment bundle is directly detected and available under the /nuxeo/api/v1/workflow path.

You can now get started on your own workflow with a POST on /nuxeo/api/v1/workflow and explore more! Let us know what you think!

 


Category: Product & Development
Tagged: How to, REST API