rConfig - API Collections
rConfig has 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.
Create a collection
Section titled “Create a collection”Creating a 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.
API Collection Form
Required fields are denoted on the form with a red asterisk.
| Field | Notes |
|---|---|
| API Collection 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 | There are 5 types of authentication available. None, Basic, Bearer Token, Api Token, Request token. These are described in more detail below. |
| Vendor | The vendor of the API endpoint. This is useful for filtering and categorizing API endpoints. |
| Command Group | 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. |
| Retry Count | The number of times to retry the API request if it fails. |
| Retry Delay | The number of milliseconds to wait between retries. |
| 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. |
Authentication Type
Section titled “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 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 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 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. |
Adding Credentials
Section titled “Adding Credentials”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.
API Add 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 from 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 Test
Adding API Endpoints
Section titled “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.
API Create Endpoint
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 Endpoint Form