Cette section détaille les endpoints pour créer, lister, modifier et supprimer les annotations sur des points de données spécifiques.
Lister les annotations d'une métrique
Description
Cette requête permet de récupérer toutes les annotations associées à une métrique sur une période donnée.
GET /v2/annotations
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:read.
Paramètres
datasource (string, obligatoire) : Source de données de la métrique.
metricName (string, obligatoire) : Nom de la métrique concernée.
start (date-time, optionnel) : Date de début de la période de recherche.
end (date-time, optionnel) : Date de fin de la période de recherche.
timezone (string, optionnel) : Fuseau horaire pour la recherche (défaut: Europe/Paris).
paginationKey (string, optionnel) : Clé pour obtenir la page de résultats suivante, fournie par la réponse précédente.
Ces paramètres doivent être ajoutés à la fin de l'URL pour construire la chaîne de requête. Le premier est précédé d'un "?" et les suivants sont séparés par un "&".
Syntaxe générale de la requête GET :
.../annotations?datasource=[source_de_donnees]&metricName=[nom_metrique]&start=[date_debut]&end=[date_fin]
Exemple de requête
# Commande pour lister les annotations de "metric4test_ok" sur une période de 5 minutes
curl -X GET \
'https://xxx.indaba.api.indasuite.io-base.com/v2/annotations?datasource=main&metricName=metric4test_ok&start=2025-06-26T08:01:16Z&end=2025-06-26T08:06:16Z' \
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Réponses
Exemple de réponse valide (200 OK)
{
"data": [
{
"id": "cbbf298c-4599-4c25-8cb2-b17c62220767",
"timestamp": "2025-06-26T10:03:46+02:00",
"value": "Valeur mise à jour.",
"isAuthor": true,
"valueUpdate": {
"oldValue": 10.5,
"newValue": 10.6
},
"userName": "Christophe Holmes",
"created": "2025-06-26T10:05:48+02:00"
}
],
"paginationInfo": {
"count": 1,
"isComplete": true
},
"statusCode": 1010,
"message": "OK"
}
Gestion de la Pagination (isComplete) :
Veuillez vous référer au paragraphe de gestion de la pagination.
Erreurs courantes :
Veuillez vous référer à la liste des erreurs courantes.
Ajouter une annotation sur un point de donnée
Description
Cette requête permet de créer une nouvelle annotation et de l'associer à un point de donnée existant, identifié par son horodatage exact.
POST /v2/annotations
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:read.
Corps de la requête
name (string, obligatoire) : Nom de la métrique à annoter.
datasource (string, optionnel) : Source de données de la métrique.
timestamp (date-time, obligatoire) : Horodatage exact du point de donnée à annoter.
annotation (string, optionnel) : Le contenu textuel de l'annotation (max 250 caractères).
Les paramètres suivants doivent être fournis dans le corps de la requête, au format JSON.
Syntaxe générale du corps de la requête :
{
"name": "nom_de_la_metrique",
"datasource": "source_de_donnees",
"timestamp": "date_et_heure_iso_du_point",
"annotation": "votre_texte_d_annotation"
}
Exemple de requête
# Commande pour ajouter une annotation
curl -X POST \
--url 'https://xxx.indaba.api.indasuite.io-base.com/v2/annotations' \
# ----- En-têtes -----
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Corps de la requête -----
-d '
{
"name": "metric4test_ok",
"datasource": "main",
"timestamp": "2025-06-26T08:05:14Z",
"annotation": "Annotation de test"
}
'
Réponses
Exemple de réponse valide (201 OK) :
{
"data": {
"id": "e0f5d990-55a1-4c4d-9e09-c8b6555072ad",
"timestamp": "2025-07-01T13:00:50+02:00",
"value": "test_api",
"isAuthor": true,
"userName": "André Matos Calhau",
"created": "2025-07-01T13:55:05+02:00"
},
"resultCode": 1010,
"message": "OK"
}
Erreurs courantes :
Veuillez vous référer à la liste des erreurs courantes.
Mettre à jour une annotation
Description
Cette requête permet de modifier le contenu d'une annotation existante, identifiée par son ID.
PUT /v2/annotations/{id}
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:read.
Paramètres
id (uuid, obligatoire) : Identifiant unique de l'annotation à modifier.
Cette requête utilise un paramètre de chemin, qui est intégré directement dans l'URL.
Syntaxe générale de l'URL :
.../annotations/[uuid_de_l_annotation]
Corps de la requête
Les champs sont les mêmes que pour la création d'une annotation (POST /v2/annotations).
Syntaxe générale du corps de la requête :
{
"name": "nom_de_la_metrique",
"datasource": "source_de_donnees",
"timestamp": "date_et_heure_iso_du_point",
"annotation": "votre_nouveau_texte_d_annotation"
}
Exemple de requête
# Commande pour mettre à jour l'annotation avec l'ID 'cbbf298c-...'
curl -X PUT \
--url 'https://xxx.indaba.api.indasuite.io-base.com/v2/annotations/cbbf298c-4599-4c25-8cb2-b17c62220767' \
# ----- En-têtes -----
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Corps de la requête -----
-d '
{
"name": "metric4test_ok",
"datasource": "main",
"timestamp": "2025-06-26T08:05:14Z",
"annotation": "Annotation mise à jour !"
}
'
Réponses
Exemple de réponse valide (200 OK) :
{
"resultCode": 1010,
"message": "OK"
}
Erreurs courantes :
Veuillez vous référer à la liste des erreurs courantes.
Supprimer une annotation
Description
Cette requête supprime une annotation existante, identifiée par son ID.
DELETE /v2/annotations/{id}
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:read.
Paramètres
id (uuid, obligatoire) : Identifiant unique de l'annotation à supprimer.
Cette requête utilise un paramètre de chemin, qui est intégré directement dans l'URL.
Syntaxe générale de l'URL :
.../annotations/[uuid_de_l_annotation]
Corps de la requête
name (string, obligatoire) : Nom de la métrique concernée.
datasource (string, optionnel) : Source de données de la métrique.
timestamp (string, obligatoire) : Horodatage exact du point concerné.
Ces champs doivent être fournis dans le corps de la requête, au format JSON.
Syntaxe générale du corps de la requête :
{
"name": "nom_de_la_metrique",
"datasource": "source_de_donnees",
"timestamp": "date_et_heure_iso_du_point"
}
Exemple de requête
# Commande pour supprimer l'annotation avec l'ID 'cbbf298c-...'
curl -X DELETE \
--url 'https://xxx.indaba.api.indasuite.io-base.com/v2/annotations/cbbf298c-4599-4c25-8cb2-b17c62220767' \
# ----- En-têtes -----
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Corps de la requête -----
-d '
{
"name": "metric4test_ok",
"datasource": "main",
"timestamp": "2025-06-26T08:05:14Z"
}
'
Réponses
Exemple de réponse valide (200 OK) :
{
"resultCode": 1010,
"message": "OK"
}
Erreurs courantes :
Veuillez vous référer à la liste des erreurs courantes.
Gestion de la Pagination (isComplete)
Pour garantir de bonnes performances, l'API peut diviser les réponses contenant un grand nombre de résultats en plusieurs "pages". Certaines réponses contiennent un champ booléen nommé "isComplete", dans l'objet "paginationInfo" pour gérer ce cas.
Si isComplete est true : Vous avez reçu toutes les données.
Si isComplete est false : Il reste des données à récupérer. Pour obtenir la suite :
Récupérez la valeur du champ "paginationKey" dans la réponse que vous venez de recevoir.
Effectuez une nouvelle requête en y ajoutant "paginationKey" comme paramètre et en attribuant à ce paramètre la valeur récupérée.
Répétez ce processus jusqu'à ce que la réponse finale contienne "isComplete" : true.
Erreurs Courantes
Vous rencontrerez principalement les codes d'erreur HTTP suivants :
400 Bad Request : Votre requête est malformée. Cela peut être dû à un paramètre manquant, un type de donnée incorrect ou un JSON invalide. Le corps de la réponse contiendra un tableau errors détaillant le problème.
{
"errors": [
{
"error": "Type_De_L_Erreur",
"message": "Description détaillée de l'erreur spécifique."
}
],
"statusCode": 1050,
"message": "Invalid request"
}
401 Unauthorized : Votre jeton d'authentification (JWT) est manquant, invalide ou expiré. Vous devez obtenir un nouveau jeton valide.
403 Forbidden : Votre jeton d'authentification est valide, mais vous n'avez pas les droits nécessaires pour cette action. Cela peut arriver pour deux raisons :
Votre jeton n'a pas les droits (scope) nécessaires (par exemple, vous tentez d'écrire des données sans avoir le scope metrics:write).
Votre jeton a le bon scope, mais votre utilisateur (ou compte de service) n'est pas rattaché à une autorisation qui donne accès à la métrique demandée.
404 Not Found : La ressource que vous essayez d'atteindre n'existe pas. Cela se produit typiquement si vous utilisez un ID incorrect ou si vous demandez une métrique qui n'existe pas.