What is the “Documentum Rest API”?

In principle, the term Documentum REST API refers to a web interface introduced with Documentum 7 that allows access to objects and functions of OpenText Documentum. This is based on Spring-Boot, is delivered as a WAR file and must be installed on an application server – e.g. Apache Tomcat. This interface can be used to write customized clients, apps, or plug-ins of other systems.

Before the Documentum Rest API, the APIs DFS and DFC had to be used as an interface for business applications in order to interact with Documentum. DFS is based on SOAP and is therefore also a web interface, while DFC is based on Java.

The REST API consists of several residual web services that interact with OpenText Documentum. It is “hypertext-driven, server-side stateless, and content negotiable, which provides you with high efficiency, simplicity, and makes all services easy to consume” [Source: https://community.emc.com/docs/DOC-32266, date of collection: 29.11.2016 – 11:51]
Introduction to REST Services

To understand how the Documentum REST API works, the first step is to explain the basic operation of a general REST service. REST stands for Representational State Transfer and is based on a stateless, client-server and cache capable communication protocol. In almost all cases the http protocol is used. REST is additionally hypertext controlled, i.e. REST clients must have all the information they need at any given moment to decide where to forward them. Hypermedia connects resources and describes their capabilities in a machine-readable way. For this reason, a REST client only needs to know one thing to communicate with the REST server – the understanding of hypermedia.

REST itself is an architecture style for network services (web services), where complex mechanisms should be avoided as far as possible by using simple http calls.
This means that a REST web service and its functions can be called without much effort from a simple http client. A call via the browser – which is also based on an http client – is also possible if the web service has implemented a GET call for the specified service URL. It is because of the http protocol that the functions and accessibility of the REST services can be easily tested and used, for example, for the in-house development of a client whose code base can be determined by the user.

In addition, the REST API can be accessed from any client, provided that this client is on the same network and can authenticate and authorize itself. An installation of local software is not necessary for the accessibility – for the use of the functions only an http-Client must exist (e.g. browser or self-developed client).

Compared to SOAP, REST also offers a small performance advantage..

Functions of the services

The Documentum REST API is delivered with some REST services that allow you to call basic functions of Documentum. Here is a brief list of what I think are the most interesting services:
Object Service
This service allows interaction with Documentum objects inheriting from dm_sysobject, such as cabinets, folders and documents. You can use the service to display objects, create and change new objects (for example, check-out/check-in, new rendition,…) or delete objects.
Objects that do not inherit from dm_sysobject must be implemented through an extension of the REST API. Read more about this in the section Extensibility.

User Service
This service can be used to manage users, groups and ACLs. This means that user administration can also be accessed from an external source and easily adapted to your own processes and requirements.

DQL Service
The DQL web service is a service that allows you to execute DQL queries and report their results back to the client. By default, the DQL service only supports select queries for security reasons. Also for security reasons, changes to objects via DQL should be implemented using your own, secure services.

Example Call of the Object Service
Once the REST API has been successfully installed on an application server, provided the firewall rules have been set up correctly, it can be called by any client from the local network under the link “/dctm-rest” (example: http://vm-documentum-app-test:8080/dctm-rest for default Tomcat configuration). When calling up this URL, e.g. via the browser, you should then be able to see the following:

If the above link, adapted to local conditions, cannot be called either via the network or locally from the application server, the log files must be inspected. Most likely something failed during the installation of the REST API.

Clicking on the “Services” button would call “/dctm-rest/services” (example: http://vm-documentum-app-test:8080/dctm-rest/services).
The result, when the page is called up, should look something like this:

If you now call the first URL, for example, all Documentum repositories would be displayed:

The URLs contained in the entries could now be used to connect to the repositories using valid logon data, for example to execute a DQL query, check out a document, or similar.

Induction
With the appropriate knowledge of the architecture and function of REST services, training is relatively quick, since the Documentum REST API corresponds to a REST-compliant interface. In addition, OpenText provides many helpful tutorials and code examples that can be found on the Internet. OpenTexts code libraries, which are available in almost all common programming languages (Java, C#, Pyton, Swift, Ruby, Objective-C, AngularJS,…) on GitHub, complete the simple introduction.
Nevertheless, these GitHub libraries should be chosen with care, since you depend on the written code and the libraries can be adapted by the manufacturer at any time. Features could be different with a new patch and not work as before, which can lead to errors.
The other option would be to create a custom written code library that accesses the API. This ensures independence from the code libraries provided by OpenText and gives you more control over what happens in the foreground during development.

Extensibility
As already indicated in the point of the individual functions of Documentum REST Services, not every function of Documentum is enabled via the web interface described here in the standard system.
However, if functions that are urgently required for business logic are missing in the standard delivery of the REST API, they can be implemented using enhancements to the REST services. It should be noted that the familiarization is not quite as simple as, for example, for the initial entry of the creation of a document management client. However, thanks to the documentation of the REST API and good examples on the OpenText community page, most of the initial problems can be handled easily. It is implemented in Java and using the build management tool Apache Maven.

Docker Support
Since version 7.3, Documentum REST web services can officially be executed as a finished docker image in a Docker container. The support of Docker is in my opinion the right step to place the REST API as the primary web interface. Docker makes it easy to scale and migrate to other servers without much effort. For this reason, the finished REST API can be quickly integrated into the internal network and used, of course under the circumstances that the necessary Documentum infrastructure already exists.

Summary
Documentum REST web services offer a good and beginner-friendly way to interact with OpenText Documentum from self-implemented systems or clients. In my opinion, the quick training in the functionality and use of the API is especially positive. But you should be careful with special cases, because the implementation of an extension of the standard API is a time-consuming process and requires some training. The possibility of using the services from all possible programming languages and thus also with any operating system is also very nice.