Uptrends' API zal in de loop van de tijd worden verbeterd en uitgebreid. We zullen nieuwe eindpunten en methoden toevoegen als dat nodig is voor nieuwe functionaliteit.
Bij het toevoegen van nieuwe functionaliteit streven wij ernaar achterwaarts compatibel te blijven. Soms is verandering echter onvermijdelijk en is een nieuwe versie van de API mogelijk niet compatibel met wat u tot nu toe heeft gecodeerd en gebruikt. Bekijk de API Changelog regelmatig om op de hoogte te blijven van alle wijzigingen en waar nodig op wijzigingen te reageren.
Als u de documentatie van de API zoekt, bekijk dan de artikelen in de categorie Uptrends' API.
Bent u ook geïnteresseerd in de wijzigingen in de Uptrends-app, bekijk dan de algemene changelog.
Januari 2023
Versie 3 van de API heeft per januari 2023 het einde van zijn levensduur bereikt en is uitgeschakeld. U kunt de documentatie nog steeds vinden in onze knowledge base, maar versie 3 werkt niet meer. Als u bestaande scripts of procedures heeft die nog gebruikmaken van versie 3, zullen deze mislukken, en we raden u aan zo snel mogelijk over te stappen naar versie 4. Zie onze upgradehandleiding voor meer informatie over het overstappen van API versie 3 naar versie 4.
Update mei 2023: De documentatie voor versie 3 van onze API is verwijderd en is niet meer toegankelijk.
December 2022
Aanmaakdatuminformatie controleregel via de API
Het /Monitor endpoint kan onder andere worden gebruikt om definities van de controleregels in uw account op te halen (via GET /Monitor/{monitorGuid}). De response bevat nu ook een CreatedDate, die aangeeft wanneer de controleregel is gemaakt.
November 2022
Kleine wijzigingen in /Register endpoint
Zoals u misschien in onze reguliere changelog heeft gelezen, hebben we in deze release de optie toegevoegd om Uptrends API-inloggegevens te maken en in te trekken via de gebruikersinterface. Om de Uptrends API v4 af te stemmen op de gebruikersinterface hebben we 2 nieuwe opties toegevoegd aan het /Register endpoint:
- Het is nu mogelijk om een optionele beschrijving op te geven bij het registreren van een nieuw API-account door het veld
omschrijvingte gebruiken. - Het is nu mogelijk om een API-account te creëren voor een andere operator wanneer de aanroepende operator voldoende rechten heeft door het veld
operatorGuidte gebruiken.
September 2022
Aankomende wijziging: tijdstempels in de API response
Momenteel worden tijdstempels die deel uitmaken van de response voor elke API v4 call op een van de volgende twee manieren geconverteerd naar JSON:
- Het aantal milliseconden is gelijk aan 0: 2022-09-21T13:08:47
- Het aantal milliseconden is niet gelijk aan 0: 2022-09-21T13:08:47.682
Deze inconsistentie kan tot problemen leiden wanneer de data die deze tijdstempels bevatten automatisch worden geparseerd en verwerkt. Daarom brengen we een wijziging aan: het aantal milliseconden wordt niet langer weergegeven voor tijdstempels die zijn opgenomen in de API response. Voortaan hebben alle tijdstempels het formaat 2022-09-21T13:08:47.
Juli 2022
Aankomende wijziging: IPv6-adressen controlestations
Wanneer momenteel de controlestation-API wordt gebruikt om controlestationinformatie op te halen, worden de IPv4-adressen van het controlestation weergegeven als een eenvoudige lijst in een reeks, terwijl de IPv6-adressen (indien van toepassing) een lijst met objecten zijn. De IP-adressen van het controlestation Amsterdam bijvoorbeeld, worden momenteel als volgt weergegeven:
"Ipv4Addresses": [
"178.217.84.4",
"188.241.149.95",
"66.212.22.2",
"185.145.63.225",
"5.182.210.227",
"5.182.210.168"
],
"IpV6Addresses": [
{
"IpAddress": "2a01:5cc0:1:2::4"
},
{
"IpAddress": "2607:fcd0:cd40:1400::2"
}
],
In een aankomende release zullen we deze inconsistentie oplossen en de IPv6-adressen op dezelfde manier retourneren:
"IpV6Addresses": [
"2a01:5cc0:1:2::4",
"2607:fcd0:cd40:1400::2",
],
Houd er rekening mee dat als u het ophalen van IP-adressen van controlestations heeft geautomatiseerd, bijvoorbeeld voor whitelistdoeleinden, dit een belangrijke wijziging kan zijn.
Juni 2022
Aankomende IP-adressen van controlestations
De Uptrends API kan worden gebruikt om IP-adressen van controlestations op te halen, voor geautomatiseerde whitelisting. Voorheen waren responses op dergelijke requests aan onze checkpoint API doorgaans een up-to-date lijst van huidige IP-adressen van controlestations. Ons controlestationnetwerk is echter altijd in beweging. Nieuwe controlestations worden toegevoegd, bestaande controlestations worden verwijderd of verplaatst, of IP-adressen worden gewijzigd. Dat kan betekenen dat de lijst met IP-adressen die u gebruikte voor whitelisting, achterloopt tot de volgende synchronisatie, wat leidt tot onnodige fouten.
We registreren nu aankomende IP-adressen van controlestations en nemen deze op in de API-response. Op die manier is uw whitelist van te voren up-to-date.
Relationships in statistics API
Responses van de Statistics API (die kan worden gebruikt om statistische data voor uw controleregels of controleregelgroepen op te halen) bevatten nu enkele aanvullende metadata over de response. De nieuwe array Relationships bestaat al voor andere API-eindpunten en bevat aanvullende informatie over de request, zoals een link naar de Monitor of MonitorGroup API request om aanvullende informatie over de controleregel(groep) zelf op te halen.
"Relationships": [
{
"Id": "4c3a9529-7934-4978-9c36-c377b232g7hb",
"Type": "Monitor",
"Links": {
"Self": "/Monitor/4c3a9529-7934-4978-9c36-c377b232g7hb"
}
}
]
Mei 2022
Oplossing voor start-/eindparameters in statistics API
Onze API ondersteunt het ophalen van statistische controleregeldata, met de Statistics API. U kunt een vooringestelde periode opgeven waarvoor de data moeten worden opgehaald (met beschikbare waarden zoals Last24Hours) of een aangepaste periode instellen met behulp van start- en eindparameters van de URL. Met GET /Statistics/Monitor/{monitorGuid}?Start=2022-04-08&End=2022-04-09 haalt u bijvoorbeeld statistische data op voor een enkele controleregel, voor de opgegeven periode.
Er was een probleem waarbij de minutenindicator in de begin- en eindtijdstempels niet correct werd toegewezen, wat had kunnen leiden tot onvolledige (of zelfs lege) resultaten in de API-response. Dit probleem is opgelost.
Februari 2022
Update van status API
De Status API haalt statusinformatie op voor een specifieke controleregel, op basis van de meest recente controleregelcheck. Dit eindpunt kan worden gebruikt voor informatie over de huidige controleregelstatus. We hebben de rersponse zo uitgebreid dat die nu ook een waarde voor TotalTime bevat - informatie over het kengetal totale tijd voor de meest recente controleregelcheck.
Januari 2022
De juiste controleregeldata retourneren
Wanneer een niet-Administrator operator met het gebruikersrecht Gegevens bekijken voor een bepaalde controleregel die controleregeldefinitie ophaalde via de API (via GET /Monitor/{monitorGuid}), bevatte de response niet alle relevante data. Dat was onjuist, omdat dezelfde data al beschikbaar waren via de gebruikersinterface maar niet via de API, en dit is gecorrigeerd. Wanneer deze operators nu een controleregel ophalen, bevat de response waarden voor MonitorGuid, Name, MonitorType, MonitorMode, IsActive en GenerateAlert.
Augustus 2021
Aankondiging: beëindiging van versie 3 van onze API
De Uptrends API ondersteunt momenteel twee versies naast elkaar. Versie 3 is de oudere legacy-versie van onze API en versie 4 is de momenteel aanbevolen versie. Met een veel completere set functies ligt de focus van onze ontwikkeling al geruime tijd op versie 4. Daarom hebben we besloten te stoppen met versie 3 van onze API, deze wordt buiten gebruik gesteld en zal rond december 2022 niet meer beschikbaar zijn.
Voor klanten die momenteel nog actief gebruikmaken van versie 3 van onze API, moet worden opgemerkt dat deze tot die tijd nog ondersteund zal worden. We raden u echter aan om zo snel mogelijk over te stappen en versie 4 te gaan gebruiken. Om u hierbij te helpen hebben we een API v3 naar v4 upgradehandleiding geschreven, waarin wordt uitgelegd wat de belangrijkste verschillen tussen de twee API-versies zijn en hoe u deze kunt overbruggen in uw scripts en software.
Juli 2021
Belangrijke wijziging: veranderingen in in autorisatie-response OperatorGroup
Met de Uptrends API kunt u gebruikersrechten voor operators en operatorgroepen beheren, rollen toewijzen zoals Beheerder, Financiële operator of Infra-toegang toestaan. De OperatorGroup API bevat verschillende opties voor het ophalen, toevoegen of verwijderen van dergelijke rechten.
De manier waarop de gebruikersrechten worden gespecificeerd voor operatorgroepen in de API is gewijzigd, wat invloed kan hebben op het automatisch aanmaken, verwijderen of ophalen van informatie over operatorgroeprechten die u mogelijk heeft ingesteld. Momenteel werkt het ophalen van informatie over gebruikersrechten met de volgende request:
GET /OperatorGroup/{operatorGroupGuid}/Authorization
die een response van onderstaande strekking retourneert (afhankelijk van welke rechten zijn geconfigureerd voor die specifieke operatorgroep):
[
{
"AuthorizationId": "{authIdGuid1}",
"AuthorizationType": "FinancialOperator",
"OperatorGroupGuid": "{operatorGroupGuid}"
},
{
"AuthorizationId": "{authIdGuid2}",
"AuthorizationType": "AllowInfra",
"OperatorGroupGuid": "{operatorGroupGuid}"
},
...
]
Vanaf nu zal diezelfde request zijn response vereenvoudigen, door alleen de verleende gebruikersrechten en geen andere informatie te vermelden. De response zal niet langer een operatorGroupGuid of AuthorizationId bevatten (de laatste zal volledig verdwijnen, wat betekent dat er aan gebruikersrechten geen individuele GUID meer wordt toegewezen). Het zal er als volgt uitzien:
{
"FinancialOperator",
"AllowInfra",
...
}
Het toevoegen van een nieuw operatorgroepsrecht werkt momenteel door een POST-request te sturen naar:
/OperatorGroup/{operatorGroupGuid}/Authorization
met een request body die een “AuthorizationType” specificeert. De momenteel beschikbare waarden voor AuthorizationType voor operatorgroepen zijn te vinden in de Uptrends API Swagger UI, onder Models (onderaan), en vervolgens OperatorGroupAuthorizationType.
Vanaf nu kunnen nieuwe gebruikersrechten worden toegevoegd aan een operatorgroep door een POST-request te sturen naar:
/OperatorGroup/{operatorGroupGuid}/Authorization/{authorizationType}
zonder een request body op te nemen.
Het verwijderen van een recht uit een operatorgroep gebeurt momenteel door een DELETE-request te sturen naar /OperatorGroup/{operatorGroupGuid}/Authorization/{authorizationGuid} - maar zoals hierboven opgemerkt, zal “authorizationGuid” volledig verdwijnen als een entiteit en kan niet meer worden gebruikt. In plaats daarvan kunt u gebruikersrechten verwijderen door rechtstreeks naar hun naam te verwijzen in de request-URL: /OperatorGroup/{operatorGroupGuid}/Authorization/{authorizationType}
Februari 2021
Belangrijke wijziging: gevoelige waarden in Multi-step API-controleregels
Met ons controleregeltype Multi-step API kunt u meerdere opeenvolgende HTTP requests uitvoeren, waarbij elke nieuwe request een of meer stukjes data gebruikt die zijn opgehaald uit een eerdere request om zijn taak uit te voeren. Vaak behelst een van de stappen dat inloggegevens worden verstrekt om toegang te krijgen tot een bepaalde bron. In het verleden werden deze inloggegevens als voorgedefinieerde variabelen toegevoegd aan de controleregeldefinitie en vervolgens gemarkeerd als Gevoelig.
Om de veiligheid te verbeteren van de manier waarop we met dergelijke inloggegevens omgaan, gaan we die opzet niet meer gebruiken. In plaats daarvan worden de inloggegevens in de vault geplaatst. Met die wijziging wordt de optie om voorgedefinieerde variabelen als gevoelig te markeren in Multi-step API-controleregels achterhaald en zal worden verwijderd.
Dit zal invloed hebben op de manier waarop u Multi-step API-controleregels kunt maken of ermee kunt interacteren via onze API. Momenteel bevat de controleregeldefinitie voor dit controleregeltype een reeks “PredefinedVariables”, waarbij elk van de individuele variabelen een true/false booleaans “Sensitive” heeft. In de nabije toekomst zal deze booleaanse waarde uit de definitie worden verwijderd. Als u in uw account een nieuwe Multi-step API-controleregel wilt maken of een bestaande wilt bijwerken via de Uptrends API, moet dit veld niet langer worden opgenomen.
Wijziging: hernoemde routing
Voor Uptrends' API v4 hebben we een inconsistente manier om routes te benoemen. In de meeste gevallen wordt enkelvoud gebruikt, maar een enkele keer meervoud. De route bevat nu alleen nog delen met enkelvoud, bijvoorbeeld /MonitorGroup/{monitorGroupGuid}/Member in plaats van /MonitorGroup/{monitorGroupGuid}/Members.
We ondersteunen nog steeds de oude routes voor achterwaartse compatibiliteit.