API v3 to v4 upgrade guide

For a long time now, you could manage your account and monitors, or retrieve monitor data, using version 3 of the Uptrends API (API v3). Since then, we’ve introduced a newer version of our API (API v4), which includes many more features and an overall better experience.

Version 3 of our API is no longer supported, and has been disabled. We recommend you switch to version 4 as soon as possible. This article will guide you through the process, and list the key differences to keep in mind when switching API versions. In addition to some functional changes, there are some differences in terminology used, for example in monitor definitions. In care you’re using the API for things like creating or updating monitors, you’ll need to adjust the names of some fields in your request body to match the API v4 monitor definition, as an example.

Similarities

The Uptrends API v3 and API v4 are both REST APIs, which allow you to perform basic CRUD (Create, Read, Update, Delete) operations on certain Uptrends entities. Generally speaking, both APIs function in a very similar fashion, offering functionality to retrieve, create, update or delete items such as monitors in your account.

In both cases, access requires HTTP Basic Authentication based on valid Uptrends credentials. It’s worth noting, however, that API v4 requires you to create a separate API account - more on this below.

Advantages

The newer API v4 offers a much more extensive set of features than its older counterpart. Examples of functionality available in v4 that isn’t present in v3 include operator management, retrieving monitor check data, dashboard management, modifying or creating alert definitions, retrieving your SLA data, and much more! For a full overview of the functions supported by API v4, visit its Swagger page.

API v4 handles authentication slightly differently (more on that below), which means you won’t have to use your regular Uptrends credentials when setting up scripts or applications to interact with the Uptrends API.

Differences

If you’re using any scripts or applications to interact with our API, there are some key differences to keep in mind. In this section, we’ll go through these differences, so that you can adjust the setup with which you’re accessing the API accordingly.

Base URL

The API v3 base URL is https://api.uptrends.com/v3 followed by the specific operation URL. For API v4, the base URL has changed to https://api.uptrends.com/v4 followed by the specific operation URL.

For example, retrieving all monitor definitions through the API v3 requires a GET to https://api.uptrends.com/v3/probes whereas the API v4 equivalent would be a GET to https://api.uptrends.com/v4/Monitor to retrieve the same information.

Operation URLs

In the example above (retrieving all monitor definitions), you can see that the specific operation URL for this particular operation has also changed from /probes to /Monitor. Most operation URLs have changed in a similar fashion going from API v3 to v4. We’ve included a complete mapping of API v3 endpoints and their API v4 equivalents below.

Object definitions

In addition to the changes to operation URLs, the actual definitions of Uptrends entities (monitors, monitor groups, operators, etc…) have also changed. As an example, let’s look at some abridged responses from both APIs, to requests GET /probes and GET /Monitor for API v3 and v4 respectively.

The API v3 response will look as follows (some information has been omitted for brevity):

{
    "Guid": "c353669c0e3b4f818adef562894f5506",
    "Name": "Galactic Resorts FPC",
    "URL": "http://www.galacticresorts.com/",
    "CheckFrequency": 5,
    "ProbeType": "FullPageCheck",
    "IsActive": true,
    "GenerateAlert": false,
    "Notes": "Example monitor notes",
    ...
}

Compare that to the v4 response (again some information has been omitted):

{
    "MonitorGuid": "c353669c-0e3b-4f81-8ade-f562894f5503",
    "Name": "Galactic Resorts FPC",
    "MonitorType": "FullPageCheck",
    "GenerateAlert": false,
    "IsActive": true,
    "CheckInterval": 5,
    "Notes": "Example monitor notes",
    "Url": "http://www.galacticresorts.com/",
    ...
}

You can see that certain objects haven’t changed. For example, both APIs respond with a Name field, which contains the monitor’s name. However, there are certain key differences in terms used. For example, the Guid field from the v3 response has become MonitorGuid in v4, and CheckFrequency has become CheckInterval. A complete overview of differences in object definitions can be found in this article. Some of those objects are specific to certain monitor types, and are listed in separate tables.

Authentication

Our API v3 requires Basic Authentication, using the same Uptrends username/password you’d use to log into the Uptrends web application.

Authentication works slightly differently in API v4, in that you’ll have to register for a separate API account first. We’ve explained the process of registering for an account and API v4 authentication in this knowledge base article. For any calls made to API v4, you’ll need to use the credentials received as a result of the steps outlined in that article.

Comparison of operations

Below, you can find a series of tables mapping common operations in API v3 with their API v4 equivalents.

Monitor operations

Monitor group operations

Monitor status and statistics

List checkpoint servers