Met de Uptrends API kunt u controleregel(groep)-informatie rechtstreeks in uw Uptrends-account bewerken. De API is een webservice die een REST-interface gebruikt om eenvoudige CRUD-bewerkingen (Create, Read, Update, Delete) uit te voeren bij Uptrends-elementen.

U kunt er ook de gegevens van uw account mee ophalen, zoals de huidige status van uw controleregels, statistieken van de performance van uw controleregels en controleregelgroepen, en de alertgeschiedenis van uw controleregels.

Vereisten

Om de Uptrends API te kunnen gebruiken heeft u het volgende nodig:

  1. De gebruikersnaam en het wachtwoord van een Uptrends-account of de inloggegevens van een operator in dat account.
  2. Toegang tot het API-domein op: https://api.uptrends.com/v3

Toegang tot de API

U heeft toegang tot de API op de gespecificeerde URL met het Https-protocol.

Authenticatie

De API vereist Http basisverificatie om toegang te verkrijgen tot de informatie. Voor toegang hebt u een inlognaam en wachtwoord van uw Uptrends-account nodig.

De inlognaam kan de primaire inlog van uw Uptrends-account zijn of die van een operator die u binnen de account aanmaakt. Voor het uitvoeren van updates is een administratoraccount vereist (d.w.z. een operator die lid is van de groep Administrators).

Http-methodes

Op basis van de Http-methode worden de volgende functies ondersteund:

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)

Foutafhandeling

Wanneer er een fout optreedt, wordt een Http-errorcode 400 (Bad Request) teruggestuurd met een foutbeschrijving in de responsinhoud.

De API ondersteunt het versturen van data in de volgende formaten:


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

Formaat

Sommige API-handelingen sturen datum/tijd-data terug. Het formaat van deze gegevens voldoet aan de ISO 8601-norm, maar zonder tijdzone-informatie. De datums worden uitgedrukt in een lokale datum en tijd, overeenkomstig de tijdzone die is ingesteld in de Uptrends-account.

Bijvoorbeeld:

De datum en tijd 1 juni 2015 om 09:35:59 PM wordt uitgedrukt als:
2015-06-01T21:35:59

ongeacht welke tijdzone in uw account is ingesteld. Als uw tijdzone EST is (UTC -05:00), dient deze waarde te worden geïnterpreteerd als 1 juni 2015 09:35:50 PM, EST.

API-functies

Alle functies kunnen worden uitgevoerd op de volgende basis-URL:

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

De request body zou dan JSON- of XML-data moeten bevatten met de volgende inhoud:

{"Name":"Updated ProbeGroupName"}

Voor updates hoeft u alleen de velden te vermelden die u wilt wijzigen. Velden die niet worden vermeld in de request worden niet gewijzigd.

Controleregelhandelingen

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)

Velddefinitie: 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.

IsCompetitor

Boolean

Indicates whether this monitor should be included in the competitor analysis report. Allowed values: True, False

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.

 

 

 

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

Voorbeeld

Om een DNS-controleregel aan de account toe te voegen, stuurt u een POST request naar https://api.uptrends.com/v3/probes, vermeldt de benodigde basis-autenticatie, stelt de headers content type en accept in op application/json en vermeldt de volgende inhoud als de request body:

{
"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"
}

Controleregelgroephandelingen

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)

Velddefinitie: ProbeGroup

Field name Type Comments

Guid

Guid

Unique monitor group ID

Name

String

Name of the monitor group

Voorbeeld 1

To get a list of all monitor groups, perform a GET request to /probegroups. The response body contains a list of probe groups:

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

Voorbeeld 2

Om een nieuwe groep te maken, voert u een POST request to /probegroups uit. De request body dient de naam voor de nieuwe groep te specificeren:

{"Name":"My new group"}

De responsebody bevat de nieuwe groep:

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

Functies bij controlegroeplidmaatschap

De volgende methodes werken bij controlegroeplidmaatschap, bijvoorbeeld welke controleregels maken deel uit van welke groepen.

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)

Voorbeeld 1

Om alle controleregels in een groep te plaatsen stuurt u een GET-request naar/probegroups/{ProbeGroupGuid}/members. De responsbody bevat een lijst met controleregels. (data in dit voorbeeld zijn ingekort):

[
{
"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,
}
]

Voorbeeld 2

Om een controleregel aan een groep toe te voegen, stuurt u een POST-request naar /probegroups/{ProbeGroupGuid}/members. De requestbody bevat een verwijzing naar de controleregel-GUID die aan de groep wordt toegevoegd:

{
"ProbeGuid" : "c4c8f5df7d02410bb1a837ce24bb2e8b"
}

Een lijst met controlestationservers ophalen

De volgende handeling retourneert een lijst van Uptrends' controlestationservers. Deze informatie kan voor twee doeleinden worden gebruikt:

  1. De CheckpointID waarden dienen te worden gebruikt bij het specificeren van specifieke controlestations voor een controleregel.
  2. De lijst bevat de IP-adressen van elke controlestationserver. Let wel, één controlestation kan meerdere controlestationservers hebben, en dus meerdere IP-adressen.
Operation Method URL Return value

List all checkpoint servers

GET

/checkpointservers

List<CheckpointServer>

Field definition: 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.

Voorbeeld

Om de lijst met controlestationservers op te halen, voert u een GET-request uit naar /checkpointservers. De responsbody bevat een lijst met controlestations (data zijn ingekort in dit voorbeeld). Let wel, het controlestation Londen heeft in dit voorbeeld (CheckpointID = 1) twee IP-adressen.

[
{
"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"
}
]

De huidige controleregelstatus ophalen

De volgende functies retourneren één of meer controleregels en hun huidige monitoringstatus.

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

Velddefinitie: 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.

Voorbeeld

Om de status van een groep controleregels op te halen, voert u een GET-request uit naar /probegroups/{probegroupguid}/status. De responsbody bevat een lijst met statusobjecten.

[
{
"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
}
]

Statistieken van controleregelgroepen en controleregels ophalen

De volgende handeling retourneert statistische gegevens (waaronder uptime, laadtijden enzovoort, zie hieronder) van de opgevraagde controleregels over een bepaald tijdsbestek.

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>

Velddefinitie: 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 Uptime

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 number of Unknown-time in seconds

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

Example

Om de status op te vragen van een controleregelgroep over januari, februari en maart 2015, gegroepeerd per maand, voert u een GET-request uit naar /probegroups/{probegroupguid}/statistics?Start=2015/01/01&End=2015/04/01&Dimension=Month.

De responsbody bevat een lijst met statistische objecten.

[
{
"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
},
...
]

Alertgeschiedenis opvragen

De volgende handeling stuurt een lijst van de alerts die werden gegenereerd voor de controleregels in de gespecificeerde controleregelgroep, gedurende het gespecificeerde tijdsbestek.

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>

Velddefinitie: 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.

Voorbeeld

Om de alertgeschiedenis van een groep controleregels op te halen van 31 mei 2015, voert u een HET-request uit naar /probegroups/{probegroupguid}/alerts?Start=2015/05/31&End=2015/06/01

De responsebody bevat een lijst van alertobjecten.

[
{
"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 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.