Posted Sep 29 by Peng Qiu.
Updated Nov 04.

In this article, we talk about how to debug Documentum REST Services with curl.

Last activity Nov 04 by Peng Qiu.
182 views. 0 comments.

Overview

What is curl? curl is a command line tool and library for transferring data with URL syntax, supporting HTTP, HTTPS and many other network protocols. curl is free and open source software and have been integrated into many systems. The official site for curl is: https://curl.haxx.se/. Linux and Mac OS users get this tool out of the box from terminals. Windows users can get it from the official site's download page.

Preliminaries

Documentum REST Sever

Assumed that you have Documentum REST services deployed and up running at http : // localhost:8080/dctm-rest. You have a repository named repo, a full privileged test user dmadmin and password.

Terminal

Assumed that you have installed curl on your client OS. You can try the very first command curl –help to test the tool.

curl –help

curl has many command parameters. What's good for us is out of these parameters, we only need to use a few of them. This table describes parameters we will use in this tutorial.

curl help

With all these prepared, we can start the debugging.

Test

A note we need to highlight at the beginning of the test is, according to hypermedia design, it's discouraged to hardcode resource URI structures in the client code. But since the command-line tool does not have GUI help users to navigate down to link relations, we will use the hard-code URIs in these tests.

1. Get home document

The first test is to get the home document resource of the REST services. Please try with the below command.

curl http://localhost:8080/dctm-rest/services

The command should return you a JSON response of home document resource.

curl-1

It's a simple format as some optional parameters are skipped. The complete command for the sample request can be as below.

curl -X GET -H accept:* –url http://localhost:8080/dctm-rest/services

2. Choose XML or JSON

The default REST service representation is JSON, but XML is supported as well. You can require an XML response in two ways.

  • By request header

curl -H accept:application/*+xml http://localhost:8080/dctm-rest/services

  • By URL extension (support GET only)

curl http://localhost:8080/dctm-rest/services.xml

3. Get Repository

A repository resource requires the client to provide login credentials. Here we add the username and password to the repository resource request.

curl -u dmadmin:password http://localhost:8080/dctm-rest/repositories/repo

The response should be like this:

curl-repo

4. Create a new cabinet

Next, let's create a new cabinet in the repository repo. The red lines in the last screenshot shows the cabinets resource URI we are going to use in this test. I assume that the user dmadmin already gets the privilege to create cabinets. The new cabinet name would be testCab001.

curl -u dmadmin:password \
http://localhost:8080/dctm-rest/repositories/repo/cabinets \
-X POST \
-H content-type:application/json \
-d “{"properties":{"object_name":"testCab001"}}”

Please note that the request method must be POST for a creation. The content type header is required for a POST method, and here is the JSON type application/json. The request body is double quoted. And as a result, any double quote in the JSON message should be escaped by a backslash (\).
You can write the the long command in one line, but you are also allowed to write it in multiple lines for pretty looking. If you do that, don't forget to use a backslash (\) as the line separator.
And here is the result snippet. From the response, we will use the folders resource URI and documents resource URI to run test cases 5, 6, and 7, as highlighted in red lines.

curl cabinets

5. Create a new folder

With the new cabinet resource, we will create a folder in it. The new folder name is testFolder001. Here is the curl command.

curl -u dmadmin:password \
http://localhost:8080/dctm-rest/repositories/repo/folders/0c00000180008906/folders \

-H content-type:application/json \

-d “{"properties":{"object_name":"testFolder001"}}”

6. Create a new contentless document

Then we create a new document in the same cabinet. The resource URI is different, and the document name is testDoc001. Here is the curl command.

curl -u dmadmin:password \

http://localhost:8080/dctm-rest/repositories/repo/folders/0c00000180008906/documents \

-H content-type:application/json \

-d “{"properties":{"object_name":"testDoc001"}}”

This document has no contents in it, and you can observe that from the response attribute r_content_size.

create doc

In real world apps, we usually create a contentful document, right? So we will do that in test case 7.

7. Create a new contentful document

The contentful document creation in a folder is performed by issuing a multipart request, and curl supports multipart POST. The resource URI is same to step 6. In the request body,

  • the first part is a JSON document describing the document properties.
  • the second part is a local content file you want to import.

So please create a JSON file in your client OS, and name it as doc-request.json. It's content is as this.

{

“properties”: {“object_name”: “testDoc002”}

}

Next, assume that you have a PDF file in your client OS, named as sample.pdf. Now let's run the curl command.

curl -u dmadmin:password \

http://localhost:8080/dctm-rest/repositories/repo/folders/0c00000180008906/documents \

-F file=@/c/Users/pqiu/doc-request.json \

-F file=@/c/Users/pqiu/sample.pdf

You don't need to specify the content type header in the multipart request since curl will do it for you. The response will tell you that this document's content size is not zero.

create pdf

NOTE: If you are using REST 7.3 GA version, please upgrade it to 7.3 Patch 01 or later versions for this test case. curl does NOT specify the right content type in the 1st part, and REST 7.3 GA version doesn't allows clients to skip the 1st part content type.

8. Download a document content

The article Manage Document Contents in REST Services introduces how to get the content download URI from a document resource. We will construct the download URI directly here. For the content download in curl, it's better to specify an output file location; otherwise, the content binary will be printed in stdout. In this command, we export the content to output.pdf.

curl -u dmadmin:password \
http://localhost:8080/dctm-rest/repositories/repo/objects/0900000180008911/content-media \
-o output.pdf

curl will report the progress and once it is done, you can check your local directory for the output file.

download file

9. Remove a document

Removing a document is by performing a DELETE on the document resource. It's straightforward enough.

curl -u dmadmin:password \

http://localhost:8080/dctm-rest/repositories/repo/objects/090000080008910 \

-X DELETE

10. Dump and troubleshooting

Curl provides several parameters to dump the response into local files. With -D and –trace, you can dump the complete response information.

curl -u dmadmin:password \

http://localhost:8080/dctm-rest/repositories/repo/objects/0c00000180008910 \

-D out-headers.txt \

–trace out-bin.txt

Summary

In this article, we quickly went through the REST API debugging with the tool curl. Curl is very light and easy to use. Wishfully, it will help you in starting with Documentum REST Services.


Table of Contents

Your comment

To leave a comment, please sign in.