L'API Uptrends vous permet de modifier les informations des moniteurs et des groupes de moniteur directement dans votre compte Uptrends. L'API est un service web qui utilise une interface REST pour effectuer des Operations basiques de type CRUD  (Create, Read, Update, Delete) sur des entités Uptrends.

Il vous permet également de récupérer les données de votre compte. Cela comprend l'état actuel de vos moniteurs, les statistiques de performance de vos moniteurs et groupes de moniteurs et l'historique des alertes de vos moniteurs.

Conditions préalables

Pour utiliser l'API Uptrends vous avez besoin de :

  1. Le nom d'utilisateur et le mot de passe d'un compte Uptrends, ou les informations de connexion d'un opérateur dans ce compte.
  2. L'accès au domaine de l'API à l'adresse : https://api.uptrends.com/v3

Accès à l'API

L'accès à l'API se fait avec le protocole HTTPS à l'adresse de l'URL spécifié.

Authentification

L'API nécessite l'authentification HTTP de base pour obtenir l'accès à l'information. Vous avez besoin d'un nom d'utilisateur et d'un mot de passe Uptrends pour obtenir l'accès.

Le nom d'utilisateur que vous utilisez peut être celui de votre compte Uptrends, ou celui de tout opérateur de votre compte. Notez qu'il vous faut utiliser un compte administrateur (un opérateur qui est membre du groupe d'administrateurs) si vous voulez effectuer des mises à jour.

Méthodes HTTP

Les actions suivantes, basées sur la méthode HTTP, sont prises en charge :

Operation Comments Http Return Code

GET

Retrieve an item

200 (HTTP OK)

POST

Create an item

201 (HTTP CREATED)

PUT

Update an item

200 (HTTP OK)

DELETE

Remove an item

200 (HTTP OK)

La gestion des erreurs

Lorsqu'une erreur se produit, un code d'erreur HTTP 400 (Bad Request) est retourné avec une description de l'erreur dans le contenu de la réponse.

L'API prend en charge le transfert des données dans les formats suivants  :

Data format Http Content-type Override URL parameter

XML

application/xml

?format=xml

JSON

application/json

?format=json

To embed the response in a jsonp callback append ?callback=myCallback

JSV

text/jsv

?format=jsv

CSV

text/csv

?format=csv

SOAP 1.1

application/xml

?format=soap11

SOAP 1.2

application/xml

?format=soap12

Format

Certaines Operations d'API renvoient des données DateTime. Le format de ces données sera conforme à la norme ISO 8601, mais sans informations de fuseau horaire. Les données seront exprimées en date et heure local, par rapport au fuseau horaire qui a été défini dans les paramètres de compte Uptrends.

Example :

La date et l'heure du 1er Juin, 2015 21:35:59 seront exprimées ainsi : 
2015-06-01T21:35:59

indépendamment du fuseau horaire dans vos paramètres de compte. Si votre fuseau horaire est celui de Paris (UTC+01:00), cette valeur doit être interprétée comme le 1er Juin, 2015 21:35:50.

Les Operations de l'API

Toutes les Operations peuvent se faire sur la base de l'URL suivant :

URL de base : https://api.uptrends.com/v3/<operation url>

Le corps de la requête devrait contenir des données JSON ou XML avec le contenu suivant :

{"Name":"Updated ProbeGroupName"}

Pour les mises à jour, il suffit de renseigner seulement les champs à modifier. Les champs laissés vides de la requête ne seront pas modifiés.

Operations de moniteur

Operation Method URL Return value

List all monitors

GET

/probes

List<Probe>

Create monitor

POST

/probes

Probe

Get monitor

GET

/probes/{ProbeGuid}

Probe

Update monitor

PUT

/probes/{ProbeGuid}

(empty)

Delete monitor

DELETE

/probes/{ProbeGuid}

(empty)

Champ défini : Probe

Field name Type Comments

Guid

Guid

Unique monitor ID

Name

String

Name of the monitor

URL

String

URL or IP address of the website, (web/database/mail/FTP/DNS-) server to check.

Port

Integer

Port number

CheckFrequency

Integer

Time interval between individual checks, in minutes. Typically this is set to 5. Using a value lower than the minimum frequency for the account (also typically 5) returns an error.

ProbeType

Enumeration

Allowed values: Http, Https, Connect, Ping, POP3, SMTP, FTP, MySQL, MSSQL, WebserviceHttp, WebserviceHttps, DNS, FullPageCheck, RealBrowserCheck

Note: the monitor type Transaction is not supported.

IsActive

Boolean

Indicates whether the monitor is active. Inactive monitors are not measured. Allowed values: True, False

GenerateAlert

Boolean

Indicates whether to send alerts for this monitor. Allowed values: True, False

Notes

String

User-defined notes. This value is only displayed in the Uptrends application.

PerformanceLimit1

Integer

First load time limit in milliseconds.

PerformanceLimit2

Integer

Second load time limit in milliseconds.

ErrorOnLimit1

Boolean

Indicates whether to generate errors when PerformanceLimit1 is exceeded. Allowed values: True, False

ErrorOnLimit2

Boolean

Indicates whether to generate errors when PerformanceLimit2 is exceeded. Allowed values: True, False

MinBytes

Integer

The minimum number of bytes in the server response to check for.

ErrorOnMinBytes

Boolean

Indicates whether to generate errors when MinBytes is exceeded. Allowed values: True, False

Timeout

Integer

The time limit for the complete test, in milliseconds.

TcpConnectTimeout

Integer

The time limit for the initial TCP connection, in milliseconds.

MatchPattern

String

Content to check for in the response of HTTP requests. Regular expressions are allowed.

DnsLookupMode

Enumeration

How to resolve the domain name specified in the URL field. Allowed values: Local (use the checkpoint’s own DNS), Primary (use the domain’s primary DNS server).

UserAgent

String

The user agent (browser identification value) to specify for HTTP(S), Real Browser Check and Full Page Check monitors.

UserName

String

The username to specify as Basic/Digest/NTLM Authentication (when available), or the login name for FTP, FTPS or SQL monitors.

Password

String

The password to specify as Basic/Digest/NTLM Authentication (when available), or the password for FTP, FTPS or SQL monitors. Please note that the password field will always be empty when you retrieve data - you can only use this field when you specify a password.

Checkpoints

String

An enumeration of checkpoints to use for this monitor. To use all checkpoints, specify an empty value. To use specific checkpoints, list the checkpoint IDs separated by a comma, e.g.: 1,2,15,27 Note: when specifying specific checkpoints, select at least two checkpoints.

UseOnlyPrimaryCheckpoints

Boolean

Indicates whether Uptrends should limit the checkpoints you specify to primary checkpoints only. Uptrends defaults to True to limit the checkpoints to primary. To allow your monitor to run on non-primary checkpoint locations as well, specify False.

Please note: Due to technical limitations and other circumstances beyond Uptrends' control, non-primary checkpoints may suffer from reduced availability, poor bandwidth, and unpredictable connectivity. Please use this option only if you explicitly need monitoring from these locations and can accept results that are not always consistent.

 

 

 

Specific values for DNS monitors:

 

 

DNSQueryType

Enumeration

The type of DNS query. Allowed values: ARecord, CNAMERecord, MXRecord, NSRecord, TXTRecord

DNSTestValue

String

The value to query for a DNS monitor. For example, when checking an A record, this value contains the domain name to check.

DNSExpectedResult

String

The expected result of the DNS query. Regular expressions are allowed.

 

 

 

Specific values for Database monitors:

 

 

DatabaseName

String

 

 

 

 

Specific values for HTTP(S) and WebserviceHTTP(S) monitors:

 

 

HttpMethod

Enumeration

Allowed values: Get, Post

PostData

String

Content for the request body in case of a Post request.

 

 

 

Specific values for Connect monitors:

 

 

ConnectMethod

Enumeration

Allowed values: Tcp, Udp

Exemple

Pour ajouter un moniteur de DNS au compte, envoyez une requête POST à https://api.uptrends.com/v3/probes, en fournissant l'authentification nécessaire, définissez les entêtes Content-Type et Accept à application/json et mettez le contenu suivant dans le corps de la requête :

{
"Name":"DNS Test monitor",
"URL":"NS81.WORLDNIC.com",
"Port":53,
"CheckFrequency":5,
"ProbeType":"DNS",
"IsActive":true,
"GenerateAlert":false,
"Notes":"",
"PerformanceLimit1":2500,
"PerformanceLimit2":5000,
"ErrorOnLimit1":false,
"ErrorOnLimit2":false,
"Timeout":30000,
"TcpConnectTimeout":10000,
"DnsLookupMode":"Local",
"IsCompetitor":false,
"Checkpoints":"1,8,28",
"DNSQueryType":"MXRecord",
"DNSTestValue":"uptrends.com",
"DNSExpectedResult":"smtp.uptrends.com"
}

Operations sur les groupes de moniteurs

Operation Method URL Return value

List all monitor groups

GET

/probegroups

List<ProbeGroup>

Create monitor group

POST

/probegroups

ProbeGroup

Get monitor group

GET

/probegroups/{ProbeGroupGuid}

ProbeGroup

Update monitor group

PUT

/probegroups/{ProbeGroupGuid}

(empty)

Delete monitor group

DELETE

/probegroups/{ProbeGroupGuid}

(empty)

Champ défini : ProbeGroup

Field name Type Comments

Guid

Guid

Unique monitor group ID

Name

String

Name of the monitor group

Exemple 1

Pour obtenir une liste de tous les groupes de moniteurs, envoyez une requête GET à /probegroups. Le corps de la réponse contient une liste des groupes de moniteurs :

[
{
"Guid" : "680a5071c6d645a3b56945053b2d6a90",
"Name" : "All probes"
},
{
"Guid" : "b1d9f5451aa04600992dc02d36f80e40",
"Name" : "Probe group 1"
},
{
"Guid" : "25532138344a407597ad679ba1176aae",
"Name" : "My other probe group"
},
{
"Guid" : "939110bb5d514dfe95e553b8a7dc8cde",
"Name" : "Test probe group"
}
]

Exemple 2

Pour créer un nouveau groupe, envoyez une requête POST à /probegroups. Le corps de la requête doit préciser le nom du nouveau groupe :

{"Name":"My new group"}

Le corps de la réponse contiendra le nouveau groupe :

{"Guid":"bd6e2c7e8a2348dc88206460d73f3658","Name":" My new group "}

Operations sur les membres des groupes de moniteurs

Les méthodes suivantes concernent l'appartenance à un groupe de moniteurs, c'est-à-dire quels moniteurs se trouvent dans quels groupes.

Operation Method URL Return value

List all monitors in a group

GET

/probegroups/{ProbeGroupGuid}/members

List<Probe>

Add monitor to a group

POST

/probegroups/{ProbeGroupGuid}/members

{Guid, ProbeGuid}

Remove monitor from a group

DELETE

/probegroups/{ProbeGroupGuid}/members

(empty)

Exemple 1

Pour obtenir tous les moniteurs appartenant à un groupe de moniteurs, envoyez une requête GET à /probegroups/{ProbeGroupGuid}/members. Le corps de la réponse contiendra une liste des moniteurs (les données dans cet exemple ont été abrégées pour brièveté) :

[
{
"Guid" : "f1248efda52e4d8db6ac6431a4a19177",
"Name" : "Test probe 1",
"URL" : "http://www.uptrends.com",
"Port" : 80,
},
{
"Guid" : "a339b142-5a87-4a18-a718-00d679a13f5d",
"Name" : "Test probe 2",
"URL" : "https://www.uptrends.com",
"Port" : 443,
}
]

Exemple 2

Pour ajouter un moniteur à un groupe, envoyez une requête POST à /probegroups/{ProbeGroupGuid}/members. Le corps de la requête doit contenir le Guid du moniteur à ajouter au groupe :

{
"ProbeGuid" : "c4c8f5df7d02410bb1a837ce24bb2e8b"
}

Obtenir une liste des serveurs de point de contrôle

L'opération suivante renvoie une liste des serveurs de point de contrôle d'Uptrends. Cette information peut être utilisée pour deux choses :

  1. Les valeurs de CheckpointID doivent être utilisées lorsqu'il faut spécifier des points de contrôle pour un moniteur.
  2. La liste contient les adresses IP pour chaque serveur de point de contrôle. Notez qu'un point de contrôle peut avoir plusieurs serveurs de contrôle, et donc des adresses IP multiples.
Operation Method URL Return value

List all checkpoint servers

GET

/checkpointservers

List<CheckpointServer>

Champ défini : CheckpointServer

Field name Type Comments

CheckPointID

Integer

Unique ID for the checkpoint. Use this value for specifying checkpoints for a monitor.

ServerID

Integer

Only used to make the combination of CheckPointID and IP address unique. Do not use this value.

CheckPointName

String

Contains the city and country where the checkpoint server is located.

IPAddress

String

The IP address of the checkpoint server.

Exemple

Pour obtenir la liste des serveurs de point de contrôle, envoyez une requête GET à /checkpointservers. Le corps de la réponse contient une liste des points de contrôle (les données dans cet exemple ont été abrégées pour brièveté). Notez que le point de contrôle de Londres dans cet exemple (CheckpointID = 1) a deux adresses IP.

[
{
"ServerID" : 0,
"CheckPointID" : 0,
"CheckPointName" : "Amsterdam, The Netherlands",
"IPAddress" : "81.18.240.134"
},
{
"ServerID" : 10,
"CheckPointID" : 1,
"CheckPointName" : "London, United Kingdom",
"IPAddress" : "81.89.133.149"
},
{
"ServerID" : 11,
"CheckPointID" : 1,
"CheckPointName" : "London, United Kingdom",
"IPAddress" : "109.73.162.168"
},
{
"ServerID" : 20,
"CheckPointID" : 2,
"CheckPointName" : "Austin, TX, USA",
"IPAddress" : "216.139.219.45"
},
{
"ServerID" : 30,
"CheckPointID" : 3,
"CheckPointName" : "Sydney, Australia",
"IPAddress" : "202.51.170.6"
},
{
"ServerID" : 40,
"CheckPointID" : 4,
"CheckPointName" : "Tampa, FL, USA",
"IPAddress" : "66.230.202.37"
}
]

Obtenir le statut actuel d'un moniteur

Les Operations suivantes renvoient un ou plusieurs moniteurs avec leur statut actuel.

Operation Method URL Return value

List status of all monitors in group

GET

/probegroups/{ProbeGroupGuid}/status

List<Status>

Status of a single monitor

GET

/probes/{ProbeGuid}/status

Status

Champ défini : Status

Field name Type Comments

ProbeGuid

Guid

Unique ID for the monitor.

ErrorLevel

Enumeration

Values: NoError, Unconfirmed, Confirmed

ErrorDescription String Description of the current error for this monitor, or "OK" if there is no error.

LastCheck

DateTime

The timestamp of the last check that was performed for this monitor.

CheckPointID

Integer

The ID of the checkpoint server that performed the last check.

Uptime Float Uptime for this monitor, for the last 24 hours.

Exemple

Pour récupérer le statut d'un groupe de moniteurs, envoyez une requête GET à /probegroups/{probegroupguid}/status. Le corps de la réponse contient une liste d'objets de statut.

[
{
"ProbeGuid" : "2a1d74876f8247139c731e9b4dce203b",
"ErrorLevel" : "NoError",
"LastCheck" : "2015-06-07T08:56:18",
"CheckPointID" : 36
},
{
"ProbeGuid" : "fa15240ae9474cff8f3e6488678627fe",
"ErrorLevel" : "Confirmed",
"LastCheck" : "2015-06-07T08:58:18",
"CheckPointID" : 33
},
{
"ProbeGuid" : "b142467ed373f5c18f0d68d16850952f",
"ErrorLevel" : "NoError",
"LastCheck" : "2015-06-07T08:59:45",
"CheckPointID" : 55
},
{
"ProbeGuid" : "ed2a88cd280b404aab9a9167ddc5ddb0",
"ErrorLevel" : "NoError",
"LastCheck" : "2015-06-07T08:56:18",
"CheckPointID" : 18
}
]

Obtenir des statistiques pour moniteurs et groupes de moniteurs

L'opération suivante renvoie des données statistiques (sur la disponibilité, les temps de chargement, etc. - voir ci-dessous) pour les moniteurs demandés, sur la période de temps spécifiée.

Operation Method URL Return value

List statistical data for a group

GET

/probegroups/{ProbeGroupGuid}/statistics? Start=<startdate>&End=<enddate>&Dimension=<dimension>

Start: start date for the requested time period, formatted as yyyy/mm/dd End: end date for the requested time period, formatted as yyyy/mm/dd. The end date is not included in the result.

Dimension: how to group/aggregate the results. Possible values: Day, Week, Month, Year, ProbeGroup, Probe, Checkpoint, ErrorCode, ErrorLevel

List<Statistics>

List statistical data for a monitor

GET

/probes/{ProbeGuid}/statistics? Start=<startdate>&End=<enddate>&Dimension=<dimension> 

Start: start date for the requested time period, formatted as yyyy/mm/dd End: end date for the requested time period, formatted as yyyy/mm/dd. The end date is not included in the result.

Dimension: how to group/aggregate the results. Possible values: Day, Week, Month, Year, ProbeGroup, Probe, Checkpoint, ErrorCode, ErrorLevel

List<Statistics>

Champ défini : Statistics

Field name Type Comments

ProbeGuid

Guid

Unique ID for the monitor.

ErrorLevel          

Enumeration

Values: NoError, Unconfirmed, Confirmed

LastCheck

DateTime

The timestamp of the last check that was performed for this monitor.

CheckPointID

Integer

The ID of the checkpoint server that performed the last check.

Dimension

String

A value describing the dimension, according to the specified dimension in the request. Example: when a dimension ‘Month’ was specified, this field could contain “2015/01”, “2015/02”, etc. If a dimension ‘Probe’ was specified, this could contain the monitor name, etc.

SLAPercentage

Float

The SLA target uptime percentage

SLATotalTime

Float

The SLA target total load time (in seconds)

SLAOperatorResponseTime

Float

The SLA target operator response time (in minutes)

AvgOperatorResponseTime

Float

The average operator response time (in minutes)

PercentageOK

Float

The percentage of OK-time

PercentageError

Float

The percentage of Error-time

PercentageUnknown

Float

The percentage of Unknown-time

PercentageUptime

Float

The percentage of time that the monitored site's status is unknown due to pausing the monitor or while the monitor is in a maintenance window.

TotalChecks

Integer

The total number of checks

Errors

Integer

The total number of confirmed errors

UnconfirmedErrors

Integer

The total number of unconfirmed errors

Alerts

Integer

The number of alerts

SecondsOK

Integer

The total number of OK-time in seconds

SecondsError

Integer

The total number of Error-time in seconds

SecondsUnknown

Integer

The total time in seconds that the monitored site's status is unknown due to pausing the monitor or while the monitor is in a maintenance window.

AverageTotalTime

Float

The average total load time

AverageResolveTime

Float

The average resolve time

AverageConnectionTime

Float

The average connection time

AverageDownloadTime

Float

The average download time

AverageTotalBytes

Float

The average total number of bytes downloaded

Exemple

Pour obtenir le statut d'un groupe de moniteurs, pour la période de Janvier à Mars 2015, regroupé par mois, envoyez une requête GET à /probegroups/{probegroupguid}/statistiques?Start=2015/01/01&End=2015/04/01&Dimension=Month.

Le corps de la réponse contient une liste d'objets statistiques.

[
{
"Dimension" : "2015/1",
"Alerts" : 0,
"SLAPercentage" : 99,
"SLATotalTime" : 2,
"SLAOperatorResponseTime" : 15,
"AvgOperatorResponseTime" : 0,
"PercentageOK" : 95.10564,
"PercentageError" : 0.200337,
"PercentageUnknown" : 4.694026,
"PercentageUptime" : 99.79966,
"TotalChecks" : 786998,
"Errors" : 1473,
"UnconfirmedErrors" : 36925,
"SecondsOK" : 224419742,
"SecondsError" : 472733,
"SecondsUnknown" : 11076442,
"AverageTotalTime" : 1.685304,
"AverageResolveTime" : 0.004690104,
"AverageConnectionTime" : 0.176703,
"AverageDownloadTime" : 1.503535,
"AverageTotalBytes" : 13259
},
...
]

Obtenir l'historique des alertes

L'opération suivante renvoie une liste des alertes qui ont été générées pour les moniteurs dans le groupe de moniteurs spécifié, pendant la période de temps spécifiée.

Operation Method URL Return value

List alert history for all monitors in group

GET

/probegroups/{ProbeGroupGuid}/alerts? Start=<startdate>&End=<enddate>

Start: start date for the requested time period, formatted as yyyy/mm/dd End: end date for the requested time period, formatted as yyyy/mm/dd. The end date is not included in the result.

List<Alert>

Champ défini : Alert

Field name Type Comments

ProbeGuid

Guid

ID that identifies the monitor for this alert

Timestamp

DateTime

The date and time for this alert

FirstError

DateTime

The date and time of the first error that triggered this alert

AlertType

Enumeration

Value that indicates if this is an error-alert or an OK-alert. Values: error, ok

ErrorDescription String Generic name of the type of error that occurred
ErrorDetails String When available, contains more detailed information about the error that caused this alert. For HTTP(S) monitors, this contains the description of the HTTP error. For transactions, it includes the step number and name of the step which triggered the error.

Exemple

Pour récupérer l'historique des alertes pour un groupe de moniteurs, pour le 31 mai 2015, envoyez une demande GET à /probegroups/{probegroupguid}/alerts?Start=2015/05/31&End=2015/06/01

Le corps de la réponse contient une liste d'objets d'alerte.

[
{
"ProbeGuid" : "a3136b5df13740e793d428480522be7b",
"Timestamp" : "2015-05-31T16:47:25",
"FirstError" : "2015-05-31T16:37:50",
"AlertType" : "ok"
},
{
"ProbeGuid" : "a3136b5df13740e793d428480522be7b",
"Timestamp" : "2015-05-31T16:42:54",
"FirstError" : "2015-05-31T16:37:50",
"AlertType" : "error"
},
{
"ProbeGuid" : "a3136b5df13740e793d428480522be7b",
"Timestamp" : "2015-05-31T12:41:26",
"FirstError" : "2015-05-31T12:24:46",
"AlertType" : "ok"
}
]

The time in seconds that the monitored site's status is unknown due to pausing the monitor or while the monitor is in a maintenance window.