Beginner's Guide to Using the HMG/HSG 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.

Open the Postman application, and dismiss any popups/dialog boxes that appear.
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 Session API command, using the following format:
  https://<URL>:443/api/session
3. Since the Initiate Session 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 Session command.
Click the Send button.
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 Initiate Session API command again to receive a new session cookie.

Get Device Information

Before being able to manage/create routes on your Gateway, you need to get the Device ID value. Issue the Get Device Info command to receive it:

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 List of Routes API command, using the following format:
  https://<URL>:443/api/devices
Click the Send button.
Results of the command are shown at the bottom of the request. Make note of the _id value for future use.

Get List of Routes

To get a list of routes defined on your Gateway:

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 List of Routes API command, using the following format, where Device ID is the copied value from Step #3 in the "Get Device Information" procedure:
  https://<URL>:443/api/gateway/<Device ID>/routes
Click the Send button.
Results of the command are shown at the bottom of the request. Make note of any of the route, source, and destination ID values for future use.

Update a Route

When changing a route's configuration, you must first get the current route's configuration, and then use the results when issuing the update route command.

Note

Include all route configuration information when issuing the Update a Route command. For example, if you are changing the port used for the source, you must include all destination information. Else, those excluded destinations are deleted.

Get Route Configuration

To get a route's current configuration:

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 Route Configuration API command, using the following format, where Device ID is the copied value from Step #3 in the "Get Device Information" procedure and Route ID is the copied value from Step #3 in the "Get List of Routes" procedure:
  https://<URL>:443/api/gateway/<Device ID>/routes/<Route ID>
Click the Send button.
Results of the command are shown at the bottom of the request. Copy the entire contents for use in the Update a Route command.

Update a Route

To update a route's configuration:

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 Update a Route API command, using the following format, where Device ID is the copied value from Step #3 in the "Get Device Information" procedure:
  https://<URL>:443/api/devices/<Device ID>/updates
3. Since the Update a Route command requires you to supply the new route configuration, 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 command body documented in the API Reference for the Update a Route command.
6. Paste the current route configuration that was copied in Step #3 in the "Get Route Configuration" procedure into the 'fields' field.
7. Remove the read-only fields, such as the elapsedTime, id, label, started state, summaryStatusCode, summaryStatusDetails, usedBandwidth fields.
Click the Send button.
The command returns an ok status if the configuration is valid. If there are issues with the route configuration, the error message gives details of the fields that are not supported.
Ok
Error

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 Snippet link to the right of the Send button.

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