rConfig - API Collections
Brand new to V7 is the ability to backup API endpoints. This is a great feature for those who need to reach into cloud based services, or other API driven services to backup configurations and data. Once the API endpoint is configured, you can use the API Collections feature to run commands and retrieve data from the API endpoint. After the data is retrieved, you can then use the data with other rConfig features such as the config diff, or the config change features, search and compliance.
Largely the experience is the same as the device backup feature, but with a few differences. First you need to create an API Collection, after which you add credentials to the collection, and then you can create API Endpoints. Once you have an API Collection and an API Endpoint, you can then run a download which will retrieve the data from the configured API Endpoints. The process flow is as follows:
- Create an API Collection
- Add credentials to the collection
- Create/ add an API Endpoint/s to the collection
- Run a download to retrieve the data from the API Endpoints
Check out a great explainer video on our youtube channel above.
Create a collection
Creating an collection is easy. Head to the API Collections section and click the “Add Collection” button. You will be presented with a form to fill in the details of the collection. Once you have filled in the details, click the “Save” button to create the collection.
Required fields are denoted on the form with a red asterisk.
| Field | Notes |
|---|---|
| API Name | Name field. Alphanumeric characters with underscores and dashes are allowed - Min 3 characters |
| API Base URL | The base URL of the API endpoint. This is the URL that will be used to connect to the API endpoint i.e. https://v7dev1.rconfig.com/api/v2/ |
| Authentication Type | As of V7.0.0 there are 5 types of authentication available. None, Basic, Bearer Token, Api Token, Request token. These are described in more detail below. |
| Verify SSL | If the API endpoint uses SSL, you can choose to verify the SSL certificate. If you are using a self signed certificate, you may need to disable this. |
| Retry Count | The number of times to retry the API request if it fails. |
| Retry Delay | The number of mili-seconds to wait between retries. |
| Vendor | The vendor of the API endpoint. This is useful for filtering and categorizing API endpoints. |
| Category | The category of the API endpoint. This is useful for filtering and categorizing API endpoints, as well as setting scheduled tasks. |
| Tags | Tags are used to group API endpoints together. For example, you may have a tag for ‘Core’ and another for ‘Access’. You can then use these tags to filter API endpoints in the API Collections table. API endpoints belong to one or more tags. |
Authentication Type
| Type | Notes |
|---|---|
| None | No authentication is required to connect to the API endpoint. |
| Basic | Basic authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password . |
| Bearer Token | Bearer Token authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization header that contains the word Bearer word followed by a space and a token. |
| Api Token | Api Token authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization header that contains the word Api word followed by a space and a token. |
| Request Token | Request Token authentication is a simple authentication scheme built into the HTTP protocol. The client sends a username and password, to a specified auth URL. The server then returns a token to be used in subsequent requests. |
Once the collection is created, you should then setup credentials. The main API collection view is below and you will see a button to add credentials. Once you have added credentials, you can then add API Endpoints.
Adding Credentials
Credentials are added to the collection. It is assumed that a single set of credentials can be used for multiple API Endpoints. Please fill out the form with the details of the credentials. Once you have filled in the details, click the “Save” button to create the credentials. Once saved, you can then test an API Endpoint to ensure the credentials are correct form within the credentials form view. The form changes dynamically based on the auth type selected.
API Credentials form
| Field | Notes |
|---|---|
| Authentication Type | This name is defaulted to the selection you made when setting up the collection. It can be adjusted on this form in case a mistake was made |
| Username | (Request Token /Basic Auth): The username to authenticate with the API endpoint if Request Token /basic or request token auth types are selected |
| Password | (Request Token /Basic Auth):The Password to authenticate with the API endpoint if basic or request token auth types are selected |
| API Token Key | (Api Token Auth): The key to be used to authenticate with the API endpoint if api token auth type is selected |
| API Token Value | (Api Token Auth): The secret to be used to authenticate with the API endpoint if api token auth type is selected |
| Add To | (Api Token Auth): Select between the header or the query string to add the token to. If you select header, the token will be added to the header. If you select query string, the token will be added to the query string. |
| Bearer Token | (Bearer Token Auth): The token to be used to authenticate with the API endpoint if bearer token auth type is selected |
| Bearer Token Prefix | (Bearer Token Auth): The prefix to be used to authenticate with the API endpoint if bearer token auth type is selected |
| Request Token Endpoint | (Request Token Auth): The URL to send the username and password to in order to retrieve a token to be used to authenticate with the API endpoint if request token auth type is selected. |
Once you have entered your credentials, you may test the credentials. Enter the URL of the API endpoint you wish to test and click the “Test” button. If the credentials are correct, you will see a success message. If the credentials are incorrect, you will see an error message.
API Credentials form
Adding API Endpoints
API Endpoints are added to the collection. Please add one or multiple API Endpoints to the collection. Once you have added the API Endpoints, you can then run a download to retrieve the data from the API Endpoints. Open the Endpoints table from the main collection view menu. This buttons toggles you between the collection view and the endpoints view.
API Credentials form
The endpoint form is simple. enter a name for the endpoint. You can also enter an alternate filename for the download. This is useful if you want to download the data to a different filename than the default, similar to the same functionality for device commands. Select your HTTP verb (GET or POST), and enter the endpoint URL. Remembering that this is the portion of the URL that comes after the base URL.
API Credentials form
Running a Download
Once you have added the API Endpoints, you can then run a download to retrieve the data from the API Endpoints. Open the main table from the endpoints view, if this is where you are currently. Click on Download now, in the main actions menu. This will run a download for all the API Endpoints in the collection. Similar to the devices view you will find a ‘Latest downloads’ table at the bottom of the page. Click the refresh button on the table to view the latest downloads. The reste of the experience is the same as the device backup feature.
API Config download