Deploy Multiple Minion Appliances via REST API

The Appliance Service provides external REST APIs that make it easier to set up multiple Minion Appliances. The REST API lets you access the information and functions required for appliance setup (configuration, connectivity and feature profiles, instances, and so on) through GET, PUT, POST, and DELETE requests.

You can perform the following tasks using the REST API:

Activate an appliance from your subscription.
Update appliance name, profile, or geographical location.
Download appliance configuration file.
Create or delete an instance.
Create or delete a connectivity profile.
Create, edit, or delete locations.
Add Minion to your appliance.
Remove Minion from your appliance.

Each request requires an API token for authentication. After you create an API token, you must add the token secret to the X-API-KEY parameter in the HTTP header.

Note that when creating or updating, the API accepts input as JSON within the body of the request.

To view the REST API documentation, select API Documentation from the left navigation menu in the web UI. The documentation provides information on the available commands and their parameters; it also lets you try some of the commands in a test setting.

You must have an understanding of HTTP, request methods, and how to send requests (using either a command line tool or library of your choice) to use the REST API. Instructions for how to use a REST API are beyond the scope of this documentation.

Before you begin

Before you set up Minion Appliances using the REST API, review the requirements in the before you begin section.

Preconfiguration

You must follow the steps below in the Appliance Service portal:

Upload a certificate.
(Optional) Configure software update schedule.
(Optional) Create a feature profile.
(Optional) Create a Minion profile.

These tasks must be completed through the web UI. You cannot use the REST API to complete them.

Create an API token

You must create an API token to use the external REST API. The API token secret, generated at the same time as the API token, must be included as a header parameter in your queries.

You can access the token secret only when you create an API token.

To create an API token, follow these steps:

Click API Tokens in the left navigation menu.
Click Add New, specify a name for the token, and click Add New.

Creating descriptive token names helps when managing multiple tokens.
Copy and save the token secret in a secure place (for example, a password management program).

You will not be able to access the token secret again.

Update an API token

You can update only the name of a token. Consider using descriptive names for easier token management.

To update a token, follow these steps:

Click API Tokens in the left navigation menu.
Find the token that you want to update and click the Pencil symbol beside its name.
Type a new name, and click Update.

Delete an API token

If you delete an API token, you can no longer use it on REST API endpoints. You may want to delete a token if it is accidentally exposed, or as a method of revoking user access from someone who shares the token (for example, an employee who has left the organization).

To delete a token, follow these steps:

Click API Tokens in the left navigation menu.
Find the token that you want to delete and click the Trash symbol beside its name.
Click Delete to confirm deletion of the token.

Try REST API commands

The REST API documentation includes the option to try a command in a test environment. This means that you can see the response that would be generated by OpenNMS, and the associated information.

You need an API token to use this feature.

To try REST API commands, follow these steps:

Click API Documentation in the left navigation menu.
Click Authorize beside the server list, paste your API token into the Value box, and click Authorize.
Find the command that you want to try in the list, expand it, and click Try it Out.

Commands are sorted by their application (for example, commands that are used against the appliance, or against the instance) and listed with a brief explanation of their function.
Specify the appropriate information (required parameters and others as desired), and click Execute. Results are listed in the Responses area, including code snippets, returned data, and any errors or exceptions.