Public API

Documentation de références des APIs Suivi

10 minutes de lecture

Liste des APIs disponibles

Cette partie décrit la liste des API proposées par Suivi. Cette liste est accessible depuis l’url de votre site en saisissant swagger à la fin (ex : https://domain.suivi.co/swagger).

Notez que la page swagger a été enrichie avec le schéma de chaque root disponible.

API Board Mapping

L’API BoardMapping permet de :

  • Ajouter un mapping de board suite à un import récurrent
  • Mettre à jour un mapping de board,
  • Supprimer un mapping de board.

API Boards

L’API Boards permettent de faire des actions relatives aux boards telles que :

  • Mettre à jour les rôles des membres spécifiés (utilisateur et/ou équipe),
  • Rechercher la liste des boards d’un espace de travail,
  • Rechercher la vue d’un board par son nom,
  • Rechercher les mappings d’import CSV d’un board,
  • Exporter un board au format CSV,
  • Récupérer la liste des sections d’un board
  • Récupérer la liste des vues d’un board
  • Changer le rôle d’un utilisateur pour un rôle de type admin, contributeur ou visiteur
  • Inviter des utilisateurs dans un board et leur assigner un rôle,
  • Importer des données CSV dans un board,
  • Copier un board,
  • Copier un board depuis un numéro de séquence,
  • Changer le statut de partage d’une vue,
  • Connaître le statut partagé des vues d’un board,
  • Modifier les variables d’un board,
  • Retrouver la liste des variables utilisées dans un board,
  • Retrouver la liste des connexions utilisées dans un board,
  • Modifier les connexions d’un board,
  • Fournir un aperçu des boards liés qui seront dupliqués lors de la duplication d’un board,
  • Dupliquer un board et tous ses boards liés,
  • Vérifier les liens entre deux boards.

API BoardWebHook

L’API BoardWebhook permet de :

  • Connaitre les webhooks d’un board par identifiant de board,
  • Connaitre les webhooks d’un board par identifiant de webhook,
  • Ajouter un webhook,
  • Supprimer un webhook,
  • Lancer un webhook,
  • Arrêter un webhook.

API Book

L’API Book permet de :

  • Personnaliser le background du book avec une image fourni par URL ou par fichier transmis dans le blob storage,
  • Personnaliser les logos du book (petit et grand),
  • Personnaliser le thème du book (clair, uni, image),
  • Personnaliser la couleur primaire du book en cas de thème de type uni,
  • Vérifier qu'un utilisateur a le droit de voir un book et un élément de book.

API Context

L’API Context permet de connaître le contexte relatif à l’utilisateur courant.

API Tenants

L’API Tenants permet de :

  • Rechercher un tenant par nom (exact),
  • Rechercher la liste des tenants accessible par un utilisateur,
  • Mettre à jour les rôles des utilisateurs du tenant (Admin, Contributeur et Visiteur),
  • Inviter un utilisateur et lui donner un rôle sur un tenant,
  • Créer un nouveau tenant.

API Users

L’API Users permet de :

  • Rechercher un utilisateur par nom, prénom et adresse e-mail,
  • Créer, modifier un utilisateur

API Workspaces

L’API Workspaces permet de :

  • Rechercher la liste des workspaces accessibles par un utilisateur,
  • Modifier les rôles Admin, Contributeur ou Visiteur d’un utilisateur dans un workspace,
  • Inviter un utilisateur et lui donner un rôle dans un workspace,
  • Créer un nouveau workspace.

Authentification et accès aux API

Obtenir une clé API

La connexion aux APIs Suivi nécessite de renseigner une clé d’API associée à un compte utilisateur de type Admin du tenant.

Pour trouver cette clé, il vous suffit de cliquer sur l’avatar dans le tenant de travail et de choisir > Modifier mon profil, onglet API key.

Notez qu’il est possible de générer une nouvelle clé mais qu’il n’y a toujours qu’une seule clé d’API pour un tenant (l’ancienne clé est donc désactivée).

Accéder aux API Swagger

Cette partie décrit la liste des API proposées par Suivi. Cette liste est accessible depuis l’url de votre site en saisissant swagger à la fin (ex : https://domain.suivi.co/swagger).

Notez que la page swagger a été enrichie avec le schéma de chaque root disponible.

Cette clé vous sera nécessaire pour vous connecter à l’API Swagger de Suivi telle que :

🔐 Clé d’API : my-api-key Cette clé doit être incluse dans l’en-tête user-api-key de toutes vos requêtes.

Book (portail)

La section Book regroupe l’ensemble des endpoints permettant de personnaliser l’apparence et le contenu d’un book dans votre application.

Modification de l’image en arrière-plan d’un book

Il existe deux façons pour changer l’image d’arrière-plan :

  • En envoyant l’URL d’une image disponible sur internet
  • En chargeant un fichier

Modification par URL

Méthode : PUT

URL : public-api/Book/{BookId}/BackgroundImage

Paramètres :

  • L’ID du book que l’on désire modifier qui se trouve dans l’URL de la requête
  • Le JSON dans le corps de la requête qui contient l’URL de l’image

Corps de la requête :

{  "ImageUrl": "string"}

Exemple :

curl -X 'PUT' \  '[https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/BackgroundImage](https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/BackgroundImage)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{  "ImageUrl": "[https://www.image.fr/mon_image.png](https://www.image.fr/mon_image.png)"}'

Modification par chargement d’image

Méthode : POST

URL : public-api/Book/{BookId}/BackgroundImageUpload

Paramètres :

  • L’ID du book que l’on désire modifier qui se trouve dans l’URL de la requête
  • L’image sous forme de fichier dans le corps de la requête

Exemple :

Modification du logo d’un book

curl -X 'POST' \  '[https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/BackgroundImageUpload](https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/BackgroundImageUpload)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: multipart/form-data' \  -F '[email protected];type=image/jpeg'

Il y a deux logos à charger dans cette méthode :

  • Le logo classique qui s’affiche sur le book
  • Le logo responsive pour l’affichage mobile

Méthode : POST

URL : public-api/Book/{BookId}/Logo

Paramètres :

  • L’ID du book que l’on désire modifier qui se trouve dans l’URL de la requête
  • L’image sous forme de fichier dans le corps de la requête pour le logo classique
  • L’image sous forme de fichier dans le corps de la requête pour le logo responsive

Exemple :

curl -X 'POST' \  '[https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/Logo](https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/Logo)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: multipart/form-data' \  -F '[email protected];type=image/png' \  -F '[email protected];type=image/png'

Modification du thème

Il existe trois types de thème pour un book :

  • Light : Le book aura un bandeau blanc sur la gauche avec une couleur des titres au survol de la souris
  • Dark : Le book aura un bandeau de la couleur sélectionnée
  • Transparent : Le bandeau sera transparent et laissera voir l’image d’arrière-plan

Les couleurs sont définies dans un tableau de clé-valeur que vous pouvez récupérer via l’endpoint dédié (voir la section “Récupération des couleurs du thème” ci-dessous).

Méthode : PUT

URL : public-api/Book/{BookId}/Theme

Paramètres :

  • L’ID du book que l’on désire modifier qui se trouve dans l’URL de la requête
  • Le thème transmis dans le corps de la requête. Valeurs possibles :
    • Light
    • Dark
    • Transparent
  • La couleur transmise dans le corps de la requête, sous forme d’un entier correspondant à l’index de la couleur que l’on désire dans le tableau des couleurs fourni par l’API

Corps de la requête :

{  "Theme": "string",  "ColorIndex": 0}

Exemple :

curl -X 'PUT' \  '[https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/Theme](https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/Theme)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{  "Theme": "Transparent",  "ColorIndex": 5}'

Récupération des couleurs du thème

Récupération des couleurs disponibles pour le thème d’un book. L’API retourne un tableau de clé-valeur contenant l’index et la valeur hexadécimale de la couleur associée.

Méthode : GET

URL : public-api/Book/ColorPalette

Réponse :

{  "0": "#000000",  "1": "#303E4D",  "2": "#667684",  "3": "#B5BCC2",  "4": "#0652A7",  "5": "#3082B7",  "...": "..."}

Exemple :

curl -X 'GET' \  '[https://localhost:5001/public-api/Book/ColorPalette](https://localhost:5001/public-api/Book/ColorPalette)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key'

Board

La section Board regroupe les endpoints permettant de gérer les variables et connexions d’un board.

Récupération des variables

Il est possible de récupérer toutes les variables d’un board.

Méthode : GET

URL : public-api/Boards/{BoardId}/variables

Paramètres :

  • L’ID du board qui se trouve dans l’URL de la requête

Réponse :

{  "Var01": "Val01",  "Var02": "NewVal02",  "Var03": "Val03"}

Exemple :

curl -X 'GET' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/variables](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/variables)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key'

Modification des variables

icon
Important

La liste fournie remplacera les variables existantes. Il est conseillé de récupérer les variables avant puis d’envoyer la liste complète des variables que l’on désire.

Méthode : PUT

URL : public-api/Boards/{BoardId}/variables

Paramètres :

  • L’ID du board qui se trouve dans l’URL de la requête
  • JSON avec la liste des variables dans le corps de la requête

Corps de la requête :

{  "var1": "Plop",  "var2": "65536"}

Exemple :

curl -X 'PUT' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/variables](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/variables)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{  "var1": "Plop",  "var2": "65536"}'

Récupération des connexions

Il est possible de récupérer les connexions d’un board.

icon
Notes

Les informations sensibles de type secret pour les tokens ou valeurs des headers ne sont pas affichées par l’API.

La réponse affichée prend en compte les deux types de connexions existants dans l’application :

  • Connexion Azure DevOps
  • Connexion HTTP

Méthode : GET

URL : public-api/Boards/{BoardId}/connections

Paramètres :

  • L’ID du board qui se trouve dans l’URL de la requête

Exemple :

curl -X 'GET' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key'

Réponse :

{  "01JE6DY43AC7R7S2TPDAPJJ16E": {    "Id": "01JE6DY43AC7R7S2TPDAPJJ16E",    "Name": "TestFixed",    "Type": "AzureDevOps",    "Properties": {      "Organization": "statshvss",      "PersonalToken": "***"    }  },  "01JHJS7BQKH6SHMBMR7JFTNAFY": {    "Id": "01JHJS7BQKH6SHMBMR7JFTNAFY",    "Name": "TestHttp",    "Type": "Http",    "Properties": {      "BaseUrl": "[https://www.google.com](https://www.google.com)",      "Headers": [        "C",        "B"      ]    }  }}

Modification d’une connexion

La modification d’une connexion est possible mais cela demande de respecter certaines règles. Pour cela, nous avons d’abord besoin de l’ID de la connexion que l’on peut récupérer via l’API, puis de fournir un JSON correctement configuré en fonction de ce que l’on souhaite faire.

icon
Important

Il faut toujours garder le type dans le JSON, même si celui-ci ne sera pas modifié.

Actions possibles :

  • Ajouter un attribut
  • Modifier la valeur d’un attribut
  • Supprimer un attribut

Méthode : PUT

URL : public-api/Boards/{BoardId}/connections/{ConnectionId}

Paramètres :

  • L’ID du board qui se trouve dans l’URL de la requête
  • L’ID du connecteur qui se trouve dans l’URL de la requête
  • JSON dans le corps de la requête

Ajouter un attribut

Voici ce que doit comporter le JSON pour ajouter des attributs :

  • Ajout d’un attribut “BaseUrl” avec la valeur “hello”
  • Ajout d’un nouveau header qui s’appelle “X-Custom-Header” avec la valeur “maValeur”

Corps de la requête :

{  "Type": "Http",  "BaseUrl": {    "NewValue": "hello"  },  "Headers": {    "X-Custom-Header": {      "Action": "Add",      "Value": "maValeur"    }  }}

Exemple :

curl -X 'PUT' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{    "Type": "Http",    "BaseUrl": {      "NewValue": "hello"    },    "Headers": {      "X-Custom-Header": {        "Action": "Add",        "Value": "maValeur"      }    }  }'

Mettre à jour un attribut

Ici je mets à jour mon attribut BaseUrl avec une nouvelle valeur et je mets à jour mon header X-Custom-Header avec une nouvelle valeur :

Corps de la requête :

{  "Type": "Http",  "BaseUrl": {    "NewValue": "hello"  },  "Headers": {    "X-Custom-Header": {      "Action": "Update",      "Update": {        "NewValue": "Plop"      }    }  }}

Exemple :

curl -X 'PUT' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{    "Type": "Http",    "BaseUrl": {      "NewValue": "hello"    },    "Headers": {      "X-Custom-Header": {        "Action": "Update",        "Update": {          "NewValue": "Plop"        }      }    }  }'

Supprimer un attribut

Ici je supprime le header X-Custom-Header :

Corps de la requête :

{  "Type": "Http",  "Headers": {    "X-Custom-Header": {      "Action": "Remove"    }  }}

Exemple :

curl -X 'PUT' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{    "Type": "Http",    "Headers": {      "X-Custom-Header": {        "Action": "Remove"      }    }  }'

Articles associés

Cette page a-t-elle été utile ?