Using postman to work with MarkLogic ReST endpoints
23 May 2017 05:14 PM
|
|
IntroductionPostman 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 StartedStep one: Choosing a MarkLogic ReST endpoint to queryIn 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:
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 userPostman 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 credentialsAfter "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 JSONPostman 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 dataAs soon as this is set, test to ensure the content returned is JSON by running the request (using the Send button): Putting it all together1. Using postman to GET a list of API endpoints from MarkLogicIn 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 POSTUse 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:
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 ReadingMarklogic ReST API docs and blog posts... | |
|