How to Get Started with WhatsUp Gold's New RESTful API

Last month, we released WhatsUp Gold 2019.1, and with it, the addition of a powerful REST API that lets you easily integrate other systems or your own scripts with WUG.

With the new REST API, you can now use an extensive range of REST API calls to get data from WhatsUp Gold from other systems, or input data to WhatsUp Gold or have other systems make changes. The result is a huge range of automation use cases that will help IT teams be faster and more efficient. Example use cases include the ability to automatically put devices in maintenance mode before making changes, the ability to add or remove devices and monitors automatically, and more.

Best of all, REST APIs are language and platform independent, which lets them circumvent the unending need for client-server dependency maintenance, and span any combination of environments (including IoT, mobile, and much more).

So how do you get started? If you've used a REST API before, then learning WhatsUp Gold's REST API should be easy.  The API is exposed through Swagger, which lets you easily explore the API and its options.  With Swagger, you can experiment with different API calls, and learn exactly what each API expects for input, and what it produces for output.  Swagger's ‘Try it out’ feature will run an API against the live WUG server, so you can test each API and observe the results.

Below, we'll give you a brief overview of how you can get started with WUG's new RESTful API, and how you can use Swagger to explore the API and test calls. For a more in-depth guide to the API, including paths and definitions, visit our full RESTful API Guide.

What You Need to Get Started

First, you'll need to know how to communicate with our REST API. In general, this RESTful API expects the following verbs: GET (query record), PUT (create record), PATCH (modify/update record), or DELETE (remove record).

You'll also need to know the following REST endpoints, and the resources they provide:

1. /api/v1/token lets you get, renew, or refresh a session token.
2. /api/v1/device-groups gives you information about a device for a given group.
3. /api/v1/devices lets you manage, monitor, and poll devices in WUG.
4. /api/v1/product will give you product and versioning information.
5. /api/v1/devices/{deviceId}/reports/ will give a report for a given device.
   /api/v1/device-groups/{groupId}/devices/reports/ will give a report for a given group of devices.
6. /api/v1/errors is a utility endpoint for getting error template information.
7. /api/v1/monitors will let you get, configure, and apply monitor templates.
8. /swagger will give you live swagger UI interactive documentation.

Before you can get started with WUG's REST API, there are  a few basics you need:

• The hostname for a deployed WhatsUp Gold 2019 system.
• The username and password for a user on the target WhatsUp Gold system.
• Your favorite HTTP client (the examples that follow use the cURL utility).

You'll also want these URLs:

Swagger UI: http://<your-whatsup-gold-server>:9644/swagger/ui/index#/

Primary REST API endpoint: https://<your-WhatsUp-Gold-server>:9644/swagger/api/v1

Swagger API Specifications and Docs: https://<your-WhatsUp-Gold-server>:9644/swagger/docs/v1

From here you can quickly check that the REST API is already listening for requests at the WhatsUp Gold host by entering https://<your-WhatsUp-Gold-server-host>:9644/swagger/docs/v1 into your web browser (Where <your-WhatsUp-Gold-server-host> is the hostname of the WhatsUp Gold system). If this call returns a JSON object, your API is running, and you can begin the steps that follow using this hostname.

Using Swagger UI, The Interactive REST API Client

As noted above, Swagger UI provides an easy way to browse the WhatsUp Gold REST documentation with live examples, and offers a simple development client for testing WhatsUp Gold REST calls. However, it should be noted that the examples are live calls (not simulated) that run against your WhatsUp Gold Environment. If you are just testing and exploring the capabilities of the REST API for development purposes, it is best practice to run against a non-production instance of WhatsUp Gold.

To get started with Swagger, follow the steps below:

1. Open a browser to https://my-whatsup-gold-host:9644/swagger/ --Where my-whatsup-gold-host is the host where you installed WhatsUp Gold
2. Click the Login button.
3. Browse and build queries and view JSON result objects.

For a more in-depth overview, check out the video below:

curl -k --request POST --url https://my-whatsup-gold-host:9644/api/v1/token --data "grant_type=password&username=emmacurtis&password=1a2B3cA1b2C3"

{
  "access_token": "X03w.....dziTwmA",
  "token_type": "bearer",
  "expires_in": 86399,
  "refresh_token": "X03w.....dziTwmA"
}

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer X03w.....dziTwmA' 'http://my-whatsup-gold-host:9644/api/v1/device-groups/0/devices'

{
  "paging": {
    "size": 96
  },
  "data": {
    "devices": [
      {
        "hostName": "192.168.37.1",
        "networkAddress": "192.168.37.1",
        "bestState": "Up",
        "worstState": "Up",
        "name": "192.168.37.1",
        "id": "14"
      },
      {
        "hostName": "192.168.37.100",
        "networkAddress": "192.168.37.100",
        "bestState": "Maintenance",
        "worstState": "Maintenance",
        "name": "192.168.37.100",
        "id": "16"
      },
      [list shortened for purposes of documentation]
}

From here, you can set up your own scripts to use our new REST API in whatever manner you see fit. For a full technical description of the API and its capabilities,  download the WhatsUp Gold REST API Guide. Then come join us on the Progress|Ipswitch Community to share scripts and discuss your ideas. We’re eager to see just how you’re going to leverage WhatsUp Gold! Happy coding!