Journal des modifications de l'API

L’API Uptrends est améliorée et étendue au fil du temps. Selon les besoins des nouvelles fonctionnalités, nous ajoutons de nouveaux endpoints et méthodes.

Lors de l’ajout de nouvelles fonctionnalités, notre objectif est de rester compatible avec les versions antérieures. Cependant, des changements sont parfois inévitables et une nouvelle version de l’API peut ne pas être compatible avec ce que vous avez codé et utilisé jusqu’à présent. Il vous faut vérifier régulièrement le journal des modifications de l’API pour être au courant des changements et agir en conséquence si nécessaire.

Si vous voulez consulter la documentation de l’API, consultez les articles de la catégorie API Uptrends.

De même, si vous souhaitez connaître les changements apportés à l’application Uptrends, consultez le journal des modifications général.

Octobre 2023

Breaking change : métriques sur le chargement des pages pour la surveillance basée sur navigateur

Remarque : ce communiqué concerne un breaking change apporté à la commande MonitorCheck de l’API. Le changement sera implémenté le mercredi 8 novembre.

La commande MonitorCheck de l’API permet de récupérer des informations détaillées sur les vérifications effectuées par les points de contrôle. Pour la surveillance basée sur navigateur, le graphique en cascade peut être récupéré par l’appel GET /MonitorCheck/{monitorCheckId}/Waterfall, qui récupère toutes les métriques du graphique en cascade, dont les indicateurs Core Web Vitals et les temps de navigation du W3C, dès lors que ces éléments figurent dans les résultats de la recherche.

Actuellement, la commande MonitorCheck de l’API restitue les indicateurs Core Web Vitals et les temps de navigation du W3C dans deux objets JSON distincts : PageLoadMetrics et W3CNavigationTiming. À l’avenir, ces objets distincts seront combinés dans un seul tableau PageLoadMetricsCollection, comme dans l’exemple ci-dessous :

  "Attributes": {
    "PageLoadMetricsCollection": [
      {
        "CumulativeLayoutShift": 0.029,
        "FirstContentfulPaint": 2914,
        "LargestContentfulPaint": 3014,
        "TotalBlockingTime": 819,
        "TimeToInteractive": 12516,
        "TimeToFirstByte": 2068,
        "SendStart": 2059,
        "LoadEventEnd": 6721,
        "DomInteractive": 2652,
        "DomComplete": 6719
      }
    ],
    ...

Spécifier les variables dans les définitions d’alertes au moyen de l’API

Lorsque des alertes sont configurées au moyen d’une intégration personnalisée dans Uptrends, les opérateurs peuvent utiliser l’interface pour spécifier certaines variables requises dans le niveau d’escalade de la définition d’alerte, plutôt que dans les options d’intégration. Ainsi, les utilisateurs peuvent utiliser une seule intégration pour différents scénarios, par exemple pour envoyer à différentes équipes des alertes sur différents ensembles de moniteurs, avec le même contenu dans le message.

Lorsque l’option permettant de spécifier des variables dans le niveau d’escalade est sélectionnée dans les paramètres d’intégration, la variable doit être configurée lors de la configuration de l’intégration pour pouvoir être utilisée dans les paramètres de la définition d’alerte. Pour cela, un champ textuel supplémentaire s’affiche dans la liste de sélection des intégrations, dans les paramètres liés aux définitions d’alerte.

Jusqu’à présent, cette option n’était pas proposée lors de la configuration des définitions d’alerte dans l’API. Nous avons ajouté une nouvelle option à la requête /AlertDefinition/{alertDefinitionGuid}/EscalationLevel/{escalationLevelId}/Integration (qui vous permet de définir quelles intégrations sont liées à chaque niveau d’escalade dans la définition d’alerte). La nouvelle propriété sera la suivante :

{
    ...
    "VariableValues": {
        "ApiUrl": "https://api.escalationlevel-specific-url.com/alerts"
    },
    ...
}

Cette propriété est l’équivalent de cette option dans l’interface de l’application :

Configuration de la variable d’intégration dans la définition d’alerte

Septembre 2023

Changement lié aux adresses IPv6

Précédemment, lorsque vous utilisiez l’API Checkpoints pour récupérer des informations sur les points de contrôle, les adresses IPv4 des checkpoints s’affichaient sous la forme d’une liste simple dans un tableau, tandis que les adresses IPv6 (le cas échéant) étaient présentées sous la forme d’une liste d’objets. Par exemple, les adresses IP du checkpoint d’Amsterdam étaient présentées comme suit :

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

Uptrends a corrigé cette incohérence et fournit désormais les adresses IPv6 sous le même format :

    "IpV6Addresses": [
        "2a01:5cc0:1:2::4",
        "2607:fcd0:cd40:1400::2",
    ],

Si vous avez automatisé la récupération des adresses IP des checkpoints (p. ex., pour établir une liste blanche), ce changement pourrait avoir des conséquences pour vous.

Janvier 2023

La version 3 de l’API n’est plus disponible depuis janvier 2023. Sa documentation reste accessible dans notre base de connaissances, mais l’API ne fonctionne plus. Si certains de vos scripts ou procédures utilisent toujours la version, ils ne sont plus fonctionnels. Nous vous recommandons de passer au plus vite à la version 4. Pour en savoir plus sur le passage de la version 3 à la version 4, consultez notre guide dédié.

Mise à jour de mai 2023 : La documentation de la version 3 de notre API a été retirée et n’est plus accessible.

Décembre 2022

Date de création du moniteur disponible via l’API

L'endpoint /Monitor peut être utilisé pour récupérer les définitions des moniteurs dans votre compte (via GET /Monitor/{monitorGuid}), entre autres informations. La réponse inclura désormais la valeur CreatedDate, qui indique la date de création du moniteur.

Novembre 2022

Légers changements apportés au endpoint /Register

Comme vous l’avez peut-être lu dans le journal des changements récents d’Uptrends, cette version permet de créer et supprimer les identifiants de l’API d’Uptrends directement depuis l’application Uptrends. Afin de faire correspondre la version 4 de l’API d’Uptrends et l’interface utilisateur, nous avons ajouté deux nouvelles options au endpoint /Register :

Il est désormais possible d’ajouter une description lors de l’enregistrement d’un nouveau compte API, au moyen du champ Description.
Lorsque l’opérateur émettant l’appel possède les droits requis, il est aussi possible de créer un compte API pour un autre opérateur au moyen du champ operatorGuid.

Septembre 2022

Changement à venir : horodatage dans la réponse de l’API

Actuellement, les horodatages inclus dans la réponse de tout appel d'API v4 sont convertis au format JSON selon l’une des méthodes suivantes :

Le nombre de millisecondes est égal à 0 : 2022-09-21T13:08:47
Le nombre de millisecondes n’est pas égal à 0 : 2022-09-21T13:08:47.682

Cette incohérence peut entraîner des problèmes lors de l’analyse et du traitement automatiques des données contenant ces horodatages. C’est pourquoi nous avons apporté ce changement : le nombre de millisecondes ne s’affichera plus dans les horodatages inclus dans la réponse de l’API. À l’avenir, tous les horodatages auront le format suivant : 2022-09-21T13:08:47.

Juin 2022

Adresses IP à venir des checkpoints

Grâce à l’API Uptrends, vous pouvez récupérer les adresses IP des checkpoints afin d’automatiser la création d’une liste blanche. Auparavant, les réponses à ces requêtes adressées à notre API Checkpoint prenaient la forme d’une liste des adresses IP actuelles des points de contrôle. Cependant, le réseau de checkpoints d’Uptrends ne cesse d’évoluer. De nouveaux checkpoints sont ajoutés, des checkpoints existants sont déplacés ou retirés, ou des adresses IP sont modifiées. Autrement dit, la liste des adresses IP que vous utilisez pour constituer votre liste blanche risque de devenir obsolète jusqu’à la prochaine synchronisation, ce qui peut entraîner des erreurs.

Pour éviter cela, nous enregistrons désormais les adresses IP à venir et nous les incluons dans la réponse de l’API. Ainsi, votre liste blanche est actualisée à l’avance.

Relations dans l’API Statistics

Les réponses de l'API Statistics (qui permet de récupérer des données statistiques sur vos moniteurs ou groupes de moniteurs) vont désormais inclure des métadonnées concernant la réponse de l’API. Le tableau Relationships existe déjà pour d’autres endpoints de l’API. Il contient des informations supplémentaires sur la requête, comme un lien vers la requête de l’API Monitor ou MonitorGroup qui permet de récupérer des informations sur un moniteur ou un groupe de moniteurs.

        "Relationships": [
            {
                "Id": "4c3a9529-7934-4978-9c36-c377b232g7hb",
                "Type": "Monitor",
                "Links": {
                    "Self": "/Monitor/4c3a9529-7934-4978-9c36-c377b232g7hb"
                }
            }  
        ]

Mai 2022

Correction des paramètres de début et de fin dans la commande Statistics de l’API

Notre API vous permet de récupérer les statistiques liées au moniteur grâce à la commande Statistics. Vous pouvez sélectionner une période prédéfinie pour la récupération des données (avec des valeurs telles que Last24Hours), ou personnaliser une période avec des paramètres d’URL désignant le début et la fin de la période. Par exemple, l’opération GET /Statistics/Monitor/{monitorGuid}?Start=2022-04-08&End=2022-04-09 récupère les données statistiques d’un moniteur pour la période précisée.

Dans la version précédente, il y avait un problème avec l’indicateur des minutes dans les horaires de début et de fin, qui pouvait entraîner des résultats incomplets (voire vides) dans la réponse de l’API. Ce problème est désormais résolu.

Février 2022

Mise à jour de la commande Status de l’API

La commande Status de l’API récupère les informations sur le statut d’un moniteur donné d’après la dernière vérification du moniteur. Cet endpoint peut être utilisé pour obtenir des informations sur le statut actuel du moniteur. Nous avons modifié la réponse pour ajouter une valeur TotalTime (Temps total), qui fournit des informations sur les mesures de temps total issues de la dernière vérification du moniteur.

Janvier 2022

Renvoi des données de moniteur correctes

Lorsqu’un opérateur non administrateur disposant de l’autorisation Afficher les données sur un certain moniteur récupérait cette définition de moniteur via l’API (via GET /Monitor/{monitorGuid}), la réponse n’incluait pas toutes les données pertinentes. C’était une erreur, car ces mêmes données étaient déjà disponibles via l’interface utilisateur mais pas l’API. Ce problème est maintenant corrigé. Désormais, lorsque ces opérateurs récupèrent un moniteur, la réponse inclut des valeurs pour MonitorGuid, Name, MonitorType, MonitorMode, IsActive et GenerateAlert.

Août 2021

Annonce : suppression prochaine de la version 3 de notre API

L'API Uptrends prend actuellement en charge deux versions côte à côte. La version 3 est l’ancienne version de notre API, et la version 4 est la version actuellement recommandée. Avec un ensemble de fonctionnalités beaucoup plus complet, la version 4 est au centre de notre développement depuis un certain temps. Nous avons donc décidé de déconseiller la version 3 de notre API, qui sera retirée et deviendra indisponible d’ici décembre 2022.

Pour les clients qui utilisent encore activement la version 3 de notre API, notez qu’elle restera disponible jusqu’à cette date. Cependant, nous vous recommandons de passer à la version 4 dès que possible. Pour vous aider, nous avons rédigé un guide de mise à niveau de l’API v3 vers v4, qui couvrira les principales différences entre les deux versions de l’API et vous indiquera comment les intégrer dans vos scripts et logiciels.

Juillet 2021

Modification sans rétrocompatibilité : changements dans la réponse d’autorisation OperatorGroup

L’API Uptrends vous permet de gérer les [autorisations pour les opérateurs et les groupes d’opérateurs] (https://www.uptrends.fr/support/kb/compte/utilisateurs/operateurs/autorisations/) en attribuant des rôles tels que Administrateur, Opérateur financier, ou en permettant un Accès Infra. La commande OperatorGroup de l’API contient plusieurs options pour récupérer, ajouter ou supprimer de telles autorisations.

Nous avons modifié la manière dont les autorisations sont spécifiées pour les groupes d’opérateurs dans l’API, ce qui pourrait affecter toute action automatisée - création, suppression ou récupération d’informations - sur les autorisations de groupes d’opérateurs que vous avez configurées. Actuellement, la récupération d’informations sur les autorisations fonctionne avec une requête :

GET /OperatorGroup/{operatorGroupGuid}/Authorization

ce qui renvoie une réponse de cette nature (en fonction des autorisations configurées pour ce groupe d’opérateurs)

[
      {
        "AuthorizationId": "{authIdGuid1}",
        "AuthorizationType": "FinancialOperator",
        "OperatorGroupGuid": "{operatorGroupGuid}"
    },
    {
        "AuthorizationId": "{authIdGuid2}",
        "AuthorizationType": "AllowInfra",
        "OperatorGroupGuid": "{operatorGroupGuid}"
    },
    ...
]

À l’avenir, cette même requête aura une réponse simplifiée, répertoriant simplement les autorisations accordées et aucune autre information. La réponse ne contiendra plus d'operatorGroupGuid ou d'AuthorizationId (ce dernier disparaîtra complètement, ce qui signifie que les autorisations n’auront plus de GUID individuel attribué). Elle ressemblera à ceci :

{
    "FinancialOperator",
    "AllowInfra",
    ...
}

L’ajout d’une nouvelle autorisation de groupe d’opérateurs se fait actuellement en envoyant une requête POST à :

/OperatorGroup/{operatorGroupGuid}/Authorization avec un corps de requête spécifiant un “AuthorizationType”. Les valeurs actuellement disponibles pour AuthorizationType pour les groupes d’opérateurs sont disponibles dans l’interface utilisateur Swagger de l’API Uptrends, dans la section Models (en bas), puis OperatorGroupAuthorizationType.

À l’avenir, de nouvelles autorisations peuvent être ajoutées à un groupe d’opérateurs en envoyant une requête POST à :

/OperatorGroup/{operatorGroupGuid}/Authorization/{authorizationType} sans inclure un corps de requête.

La suppression d’une autorisation d’un groupe d’opérateurs se fait actuellement en envoyant une requête DELETE à /OperatorGroup/{operatorGroupGuid}/Authorization/{authorizationGuid}, mais comme indiqué ci-dessus, “authorizationGuid” disparaîtra entièrement en tant qu’entité et ne pourra plus être utilisé. À la place, vous pourrez supprimer des autorisations en vous y référant directement par leur nom dans l’URL de la requête : /OperatorGroup/{operatorGroupGuid}/Authorization/{authorizationType}

Février 2021

Modification sans rétrocompatibilité : valeurs sensibles dans les moniteurs d’API multi-étapes

Notre type de moniteur API multi-étapes vous permet d’exécuter plusieurs requêtes HTTP consécutives, où chaque nouvelle requête utilise des données récupérées d’une requête précédente pour effectuer sa tâche. Souvent, l’une des étapes va consister à présenter des justificatifs d’identité pour avoir accès à une ressource particulière. Dans le passé, ces informations d’identification étaient ajoutées à la définition du moniteur en tant que variables prédéfinies, puis marquées comme sensibles.

Afin d’améliorer la sécurité de la gestion de ces justificatifs, nous n’allons plus utiliser cette méthode. Au lieu de cela, les justificatifs seront placés dans le coffre-fort. Avec ce changement, l’option permettant de marquer des variables prédéfinies comme sensibles dans les moniteurs API multi-étapes devient obsolète et sera supprimée.

Cela modifiera la manière dont vous pourrez créer ou interagir avec les moniteurs API multi-étapes par le biais de notre API. Actuellement, la définition de moniteur pour ce type de moniteur contient un tableau “PredefinedVariables”, où chacune des variables individuelles a une valeur booléenne vrai/faux “Sensitive”. Dans un avenir proche, ce booléen sera supprimé de la définition. Si vous souhaitez créer ou mettre à jour un moniteur API multi-étapes existant dans votre compte par le biais de l’API Uptrends, ce champ ne doit plus apparaître.

Changement : noms des chemins d’accès

Pour Uptrends APIv4, la manière de nommer les chemins n’est pas toujours cohérente. Dans la plupart des cas, le singulier est utilisé, mais parfois c’est le pluriel. L’itinéraire ne contient plus que du singulier, par exemple, /MonitorGroup/{monitorGroupGuid}/Member plutôt que /MonitorGroup/{monitorGroupGuid}/Members.

Les anciens chemins fonctionneront toujours pour la compatibilité ascendante.

Journal des modifications de l’API