Introduction

Nowadays, restful APIs are used in any product, almost. In the era of web services, it is normal to have the same for documentum. In this blog I’ll show you a part of this API for documentum, how to test it, how to use it, and what could be done with it.

Installation

In order to install the Documentum REST API, download the war file from OpenText website and put it into an application server. Here is the list of supported products:

• Tomcat
• Vmware vFabric tc Server
• Weblogic
• IBM Websphere
• JBoss

You’ll need to setup the dfc.properties for it to connect to the wanted docbase. You can change it in the WAR directly or in the exploded folder when deployed (e.g. in Tomcat). You’ll want to edit rest-api-runtime.properties as well if you need to specify some config for the API behaviour (i.e. the authtentication mecanism: Basic, Kerberos aso).

Configuration

Authentication

First of all, you’ll need to choose how you will login to the docbase. I don’t have a kerberos infra setup so I’ll go for the Basic method. As the name states it, it’s really simple and basic. During each calls to the REST services you’ll send HTTP requests. So just put an header called “Authorization” and specify it’s value like follow:

Basic BASE64{${username}:${password}}

The “BASE64” part must be the result of the encryption in BASE64 of the username and password separated by a “:” character. The user must be declared in the docbase. Note that you will only be able to get results that the user is allowed to retrieve. So if you want to browse and access all content of the docbase you should use a user with priviledges. At the end you should end up with something like this as the value of the header:

Basic ZG1hZG1pbjpkbWFkbWluMQ==

First call

There are two result formats that you can receive from the docbase: JSON, XML. You can set it in the runtime properties file. Usually we set it to the default JSON.

As you know you have several HTTP request types, and in RESTful it will end up in several actions:

• GET (retrieve data)
• PUT (Update data)
• POST (Create data)
• DELETE (Remove data)

So for our first call we choose GET in order to retrieve some info, like the list of available repositories. Here is how the HTTP request will look like:

[GET] http://HOSTNAME:PORT/dctm-rest/repositories

You’ll get a JSON in return that should look like this:

{
	"id": "http://HOSTNAME:PORT/dctm-rest/repositories",
	"title": "Repositories",
	"author": [
		{
			"name": "EMC Documentum"
		}
	],
	"updated": "2018-09-28T14:41:29.686+00:00",
	"page": 1,
	"items-per-page": 1000,
	"total": 1,
	"links": [
		{
			"rel": "self",
			"href": "http://HOSTNAME:PORT/dctm-rest/repositories"
		}
	],
	"entries": [
		{
			"id": "http://HOSTNAME:PORT/dctm-rest/repositories/DBI01",
			"title": "DBI01",
			"summary": "DBI01 Repo",
			"updated": "2018-09-28T14:41:29.739+00:00",
			"published": "2018-09-28T14:41:29.738+00:00",
			"links": [
				{
					"rel": "edit",
					"href": "http://HOSTNAME:PORT/dctm-rest/repositories/DBI01"
				}
			],
			"content": {
				"type": "application/vnd.emc.documentum+json",
				"src": "http://HOSTNAME:PORT/dctm-rest/repositories/DBI01"
			}
		}
	]
}

The interesting part is in the “entries” data. You’ll have here the list of repositories to which your user will have access to. In my example I only have “DBI01”, you can see the name of the docbase in the “title” attribute. Also in the “links” you’ll have the link to navigate (in HTTP) to the repository object, here: http://HOSTNAME:PORT/dctm-rest/repositories/DBI01.

Navigating from link to link you’ll be able to browse the repo (e.g. you would be able to create an HTML application to navigate through a repository).

Create a document

Create the metadata

You can create a document in a specific folder selecting a specific repository, getting the folder’s r_object_id, and sending the following query as POST:

[POST] http://HOSTNAME:PORT/dctm-rest/repositories/DBI01/folders/0c03d09080001921/documents

You’ll have to enter some attributes in order to fill out info about the file, put it in the message body as json like:

{"properties":
	{"object_name":"DummyDocument",
	"r_object_type":"dm_document"}
}

In addition to the “Authorization” header you’ll have to specify the “Content-Type” to be:

application/vnd.emc.documentum+json

At this point you only created the metadata of the file, so it exists in the repo but you cannot download or checkout the file as no content is set for it! When you executed the POST, you’ll get a json in return with the info of the created object, you can get it’s r_object_id attribute as we will need it afterwards in order to add a content to the metadata. You can also check the headers where you can find the Location of the object:

Header: Location

http://HOSTNAME:PORT/dctm-rest/repositories/DBI01/documents/0903d0908000ed1c

JSON result:

...
"r_object_id": "0903d0908000ed1c"
...

Add a content

Now as we have the r_object_id we can add a content. It’s also a POST query as we are creating content, just put a file in the body of the query or just write the content as text in the body to create a text file. Then use this query with the previous r_object_id:

[POST] http://HOSTNAME:PORT/dctm-rest/repositories/DBI01/objects/0903d0908000ed1c/contents

You should get a json in return with the name: “content” and some info about the created object. You can view the document by simply executing a GET on the object directly:

[GET] http://HOSTNAME:PORT/dctm-rest/repositories/DBI01/objects/0903d0908000ed1c

Delete a document

In order to delete a document, it’s quite simple, you only need it’s r_object_id and execute a DELETE query like:

[DELETE] http://HOSTNAME:PORT/dctm-rest/repositories/DBI01/objects/0903d0908000ed1c

Note that you will receive nothing in return if it suceeded. Otherwise you’ll get an error or a 404 if it was already deleted.