Using the API

Overview

The UpGuard Core API provides a feature rich method of interacting with many Core features in a programatic way. The API comes in two versions, version 1 and version 2. Version 1 is not recommended for use as it has been deprecated, but still exists for backwards compatibility. For more information on the differences between the two versions, please see the section below on API v1 vs. V2.

Authentication is achieved via an API key and secret pair and can be provided to the server using either the Authentication header, or using Basic Auth.

Accessing API Key and Secret

An API key and secret key are used to interact with all endpoints. Only one secret key is created per account and it is automatically generated when you enable or disable the the API through the account management page.

1. To access your account keys, firstly login and then click on your Account Name in the top right of the website, then click Manage… from the drop down list.
   
2. Click on your account name to bring up the account management page.
3. Finally, enable API Access to generate your API Secret Key.

Authentication Methods

There are 2 ways to form the API request headers for Authorization:

• The Authorization request header is formed by concatenating your Service API Key and your Secret Key:

Authorization: Token token="[Service API Key][Secret Key]"

• Alternatively, the Authorization request header can also be formed with the Basic Auth method, where the username is supplied with the Service API Key, and the password will be your Secret Key.

cURL Example

Authorization Header

curl -H 'Authorization: Token token="[Service API Key][Secret Key]"' https://app.upguard.com/api/v2/nodes.json

Basic Auth

curl --user [Service API Key]:[Secret Key] https://app.upguard.com/api/v2/nodes.json

API v1 vs. v2

While v1 and v2 of the UpGuard API are similar, and in many cases identical, there are important differences which are noted here.

• Parts of the v1 API have been deprecated. The v1 API as a whole is no longer under active development, and will not receive new features or bugfixes.

• The v2 API is capable of working with parts of UpGuard that v1 is not. For example, v2 has support for Connection Manager Groups and Policies.

Incompatible Changes

• Some URLs have changed for more consistent behavior across the API. For example, the Connection Manager API index is queried at /api/v2/connection_managers.json instead of /api/v1/connection_managers.

• The structure of JSON data returned by API endpoints may differ between v1 and v2.
  • Sometimes this is additive, and should not affect code written for the v1 API. For example, the v2 Nodes API returns the same data as v1, with extra data fields added.
  • However, some endpoints return very different data.
• Some v1 API endpoints have been deprecated. Deprecated v1 APIs are marked as such in the API v1 endpoint documentation.

If you are considering a migration, please consult the documentation for each API endpoint that you require.

Usage Recommendations

Because v1 of the API is deprecated, and does not include some of the functionality provided in v2, we encourage you to use v2 for new development.

However, v1 is not end-of-life and will continue to work normally for the foreseeable future. If v1 provides the features that you require, it is not necessary to migrate at this time.

Saving Requests

If you are planning to use the API for development work or for an extended period of time, using an app such as Postman can help you save time by saving queries and nicely formatting (and presenting) JSON responses.

HTTP Status Code Summary

Ignoring self-signed Certificates

If your appliance is using a self-signed certificate, you may need to implicitly trust the server before making an API request. Simply add this to the script in question, and all web requests will ignore the self-signed certificate.

cURL

Add the -k option to ignore SSL certificate checks.

PowerShell

add-type @"
    using System.Net;
    using System.Security.Cryptography.X509Certificates;
    public class TrustAllCertsPolicy : ICertificatePolicy {
        public bool CheckValidationResult(
            ServicePoint srvPoint, X509Certificate certificate,
            WebRequest request, int certificateProblem) {
            return true;
        }
    }
"@
[System.Net.ServicePointManager]::CertificatePolicy = New-Object TrustAllCertsPolicy

Ruby

If using HTTParty, add the :verify => false option.

response = HTTParty.get(url, :headers => <auth_headers>, :verify => false)

Python

If using the requests python library then append verify=False as an option all requests.

response = requests.get(url, headers=headers, verify=False)

GoLang

If using the default http package in GoLang, disable all SSL checks before running any API calls by using this line of code.

http.DefaultTransport.(*http.Transport).TLSClientConfig = &tls.Config{ InsecureSkipVerify: true }

Ruby SDK

If you are using the Ruby SDK, the optional 4th param of the Account constructor allows you to ignore SSL certificate checks (defaults to false if omitted).

o = UpGuard::Account.new("https://me.upguard.com", "api_key", "sec_key", true)

Python SDK

If you are using the Python SDK, the optional 4th param of the Account constructor allows you to also ignore SSL checks (defaults to false).

o = upguard.Account("https://me.upguard.com", "api_key", "sec_key", True)