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:
- Select Post in the request type dropdown menu.
Enter the Request URL for the Initiate Session API command, using the following format:
https://<URL>:443/api/session
Since the Initiate Session command requires you to supply the username and password, click the Body tab.
Click raw in the body format, and select JSON in the format type dropdown menu.
- 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:
- Select Get command type.
- 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:
- Select Get command type.
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.
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: