Beginner's Guide to Using the HMP REST API

This tutorial explains the basics for using the REST API commands that are documented in the REST API Integrator's Guide.

Prerequisites

• Download and install the Postman API Development Environment

Note

Postman is used in this tutorial. However, any API tool is supported.

Logging In

To access the API commands, you must first login and obtain a session cookie. This cookie must be included in the header of all subsequent API commands, which Postman does automatically.

1. Open the Postman application, and dismiss any popups/dialog boxes that appear.
2. In the main window, create a new request as shown in the following figure:
   1. Select Post in the request type dropdown menu.

   2. Enter the Request URL for the Initiate User Session API command, using the following format:
      https://<HMP URL>/apis/authentication/login

   3. Since the Login command requires you to supply the username and password, click the Body tab.

   4. Click raw in the body format, and select JSON in the format type dropdown menu.

   5. In the textbox enter the username and password using the format documented in the API Reference for the Initiate User Session command.
   
3. Click the Send button.

4. If successful, a session cookie is returned in the request. Click the Cookies tab to see the response.
   

Postman will save this session cookie and use it for any subsequent commands.

Running Other Sample API Commands

After logging in, other commands can now be run.

Note

If you receive a HTTP 401 Unauthorized or a 404 Not Found response, your session cookie may have expired. Issue the login API command again to receive a new session cookie.

Get List of Sources

To get a list of sources defined on your HMP:

1. Create a new request by clicking the + tab, and populate the fields as follows:
   1. Select Get command type.

   2. Enter the Request URL for the Get the Source List API command, using the following format:
      https://<HMP URL>/apis/sources

   
2. Click the Send button.

3. Results of the command are shown at the bottom of the request. Make note of the id value for future use.
   

Create a Session and Assign Source

Creating a new session and assigning a source requires two API commands.

Create a Session

To create a session:

1. Similar to the previous command, create a new request by clicking the + tab, and populate the fields as follows:
   1. Select Post command type.

   2. Enter the Request URL for the Create a Session API command, using the following format:
      https://<HMP URL>/apis/sesssions

   3. Click the Body tab and enter the channel label:

   4. Click raw in the body format, and select JSON in the format type dropdown menu.

   5. In the textbox enter the desired session title and description using the format documented in the API Reference for the Create a Session command.
   
2. Click the Send button.
3. A HTTP 201 Created response is returned along with a session id value in the results window. Copy the "id" value for use in the next section.
   

Assign Source to Session

To assign a source to the created session:

1. Create a new request by clicking the + tab, and populate the fields as follows:
   1. Select Post command type.

   2. Enter the Request URL for the Add a Session Source API command, using the following format, where session id is the copied value from Step #3 in the "Create the session" procedure.
      https://<HMP URL>/apis/sessions/<session id>/sources

   3. Click the Body tab and enter the source id that was noted in Step #3 in the Get List of Sources procedure using the format defined in Add a Session Source.

   

2. Click the Send button.
3. A HTTP 201 Created response is returned, as well as the session details in the results window.
   

   

Get Thumbnail Image from a Session

To get a thumbnail image from a session:

1. Create a request and populate the fields as follows:
   1. Select the Get command type.

   2. Enter the Request URL for the Get Thumbnail Image for a Session API command, using the following format, where session id is the copied value from Step #3 in the "Create the session" procedure.
      https://<HMP URL>/apis/sessions/<session id>/thumbnail

   

2. Click the Send button.
3. A thumbnail of the specified session is returned in the results window:
   

   

Converting Postman Commands to Other Languages

You can easily generate code snippets for other programming languages in Postman. After confirming your command is valid with a successful response, click the Code link under the Send button.

Various programming languages are available. Simply copy/paste the code for use in your desired software: