Knowledgebase: App Services
Using postman to work with MarkLogic ReST endpoints
23 May 2017 05:14 PM

Introduction

Postman is a valuable tool for testing the behaviour of HTTP connections and for exploring MarkLogic through its ReST-based APIs.  

Postman can be downloaded as a Chrome (browser based) application or as a standalone application from https://www.getpostman.com/

Getting Started

Step one: Choosing a MarkLogic ReST endpoint to query

In this example, we're using the standard ReST endpoint that ships with MarkLogic Server version 7 and above.  For this example, everything is already set up to connect immediately on port 8000.  

We are going to use the ReST API to access one of the many features exposed by MarkLogic's ReST API - using an HTTP GET request to get the configuration properties using ReST:

If you're running this example locally, the endpoint you will be accessing will be:

http://localhost:8000/LATEST/config/properties

If you run this in your browser, you'll see something like this getting returned:

<rapi:properties xmlns:rapi="http://marklogic.com/rest-api">
<rapi:content-versions>none</rapi:content-versions>
<rapi:debug>false</rapi:debug>
<rapi:document-transform-all>true</rapi:document-transform-all>
<rapi:document-transform-out/>
<rapi:update-policy>merge-metadata</rapi:update-policy>
<rapi:validate-options>true</rapi:validate-options>
<rapi:validate-queries>false</rapi:validate-queries>
</rapi:properties>

We can use Postman to do the same work; first set the HTTP method to GET and enter the API endpoint URL as per the example below:

Step two: configuring Digest authentication for your user

Postman will need to perform authentication on your behalf; we can set this up to use Digest authentication to communicate with MarkLogic Server.  

Start by selecting the Authorization tab and where you see the Type dropdown, select Digest Auth:

Step three: configure your user credentials

After "Digest Auth" has been set, input your credentials: username and password and use public for the Realm:

Step four: submit the request and view the response (as XML)

Use the Send button and note that you can view the HTTP Headers passed and the HTTP Response body: 

Step five: understanding content negotiation - returning JSON

Postman will also allow you to configure headers; we're going to add an Accept header and request that the HTTP response from MarkLogic is JSON.  To do this, use the dropdown box to select the correct mimetype for JSON (application/json):

Step six: verifying the JSON response data

As soon as this is set, test to ensure the content returned is JSON by running the request (using the Send button):

Putting it all together

1. Using postman to GET a list of API endpoints from MarkLogic

In this case, we're going to call the following MarkLogic ReST API endpoint to list all configured ReST Application Servers:

http://localhost:8002/LATEST/rest-apis

Set up Postman to call this endpoint:

2. Change the GET to a POST

Use the dropdown to change the HTTP method from GET to POST:

Note that you should now get an exception (HTTP 400) in the response body and the message code thrown by MarkLogic Server will be RESTAPI-INVALIDCONTENT:

As we're now performing a POST, the API is telling us that it's expecting a payload to be sent along with the request; in this case, the POST should be accompanied with information about the particular resource we're going to create.

If we want to create a new ReST application server, here are a minimal set of parameters that can be sent over to MarkLogic Server:

<rest-api xmlns="http://marklogic.com/rest-api">
   <name>myTest</name>
   <database>Documents</database>
   <port>9111</port>
</rest-api>

In the example above, we're specifying the Application Server name, the default database and the port 

If we look at the Body tab in Postman, we want to set the body format as raw and ensure that XML (application/xml) is specified as the content type for the body.

Finally, add your payload content and press Send

If everything went to plan, you should find that a 201 Created status is returned by MarkLogic Server.

Further Reading

Marklogic ReST API docs and blog posts...

https://docs.marklogic.com/guide/rest-dev/service

(2 vote(s))
Helpful
Not helpful

Comments (0)