Introduction
API signifie Application Programming Interface. Une API vous permet d’interagir de manière programmatique avec certaines parties de RESPONSUM et d’échanger des informations. RESPONSUM fournit des endpoints API pour les fonctionnalités/données principales, qui peuvent être utiles pour certaines automatisations et intégrations avec d’autres systèmes/outils (opérationnels).
Ces endpoints API seront mis à jour/étendus au fil du temps, mais nous veillerons à ce qu’ils restent rétrocompatibles afin que les intégrations créées continuent de fonctionner. Si vous avez des questions ou des demandes de nouveaux endpoints, contactez-nous via support@responsum.eu.
Démarrage rapide
- Assurez-vous que les API sont activées pour votre tenant. Elles sont désactivées par défaut ; vous devrez donc peut-être contacter support@responsum.eu.
- Une fois activées, vous pouvez aller dans settings > setup > my organization ; en cliquant sur le niveau supérieur, vous pourrez trouver votre « tenant key » dans les propriétés.
- Vous pouvez maintenant trouver notre documentation sous settings > integrations > API documentation
- Créez un jeton API en allant dans settings > integrations > API tokens
- Des exemples de code JavaScript Node.JS sont disponibles ici : https://github.com/RESPONSUM-BE/RESPONSUM-api-example – Vous pouvez utiliser la tenant key + le jeton API généré précédemment pour essayer.
- Vous trouverez un schéma dans notre Help Center expliquant les principaux concepts de RESPONSUM. Cela vous aidera à comprendre notre structure de base afin de retrouver facilement les concepts.
- Voici une brève introduction à quelques concepts importants ; vous pouvez en lire davantage ci-dessous.
- UUID : Vous pouvez créer vos propres UUID ou générer des UUID au format RESPONSUM via
https://api.responsum.app/v1/[tenant key]/uuids/[amount]– Si vous générez vos propres UUID, assurez-vous absolument qu’ils sont 100 % uniques ; il existe des bibliothèques pour cela si nécessaire, n’utilisez pas math.random 🙂 - Objets de lien : RESPONSUM n’utilise PAS une modélisation relationnelle classique. Les liens entre éléments sont des objets pour nous.
- Versioning : Presque tous les modèles RESPONSUM sont versionnés. Cela signifie que nous suivons les modifications de tout. Des API spécifiques sont disponibles pour gérer cela ou demander des informations sur l’historique des versions et l’approbation d’un objet.
- Champs calculés : RESPONSUM calcule côté serveur un certain nombre de champs. Cela se fait automatiquement. Lors de la récupération d’un objet, nous vous fournirons également nos champs calculés. Vous ne pourrez pas les mettre à jour manuellement.
- Piloté par événements : Tout ce qui se passe dans RESPONSUM (création, mise à jour, suppression, version, …) commence par un événement. Vous pouvez utiliser des webhooks pour vous abonner à toutes sortes d’événements. En pratique, tout ce qui se passe dans RESPONSUM peut déclencher une réaction via les API de webhooks.
- UUID : Vous pouvez créer vos propres UUID ou générer des UUID au format RESPONSUM via
- Il est toujours recommandé de lire le manuel complet avant de vous lancer. Le monde est dangereux et vous ne voulez pas vous blesser ; mais avec ce démarrage rapide, j’espère que vous y arriverez. Bonne chance !
Premiers pas
S’assurer que l’API est activée pour votre tenant
Par défaut, l’API RESPONSUM est désactivée au niveau du tenant et masquée dans notre interface.
Pour activer l’API pour votre tenant, vous devrez contacter notre équipe support via support@responsum.eu, qui pourra l’activer et répondre aux questions que vous pourriez encore avoir après lecture de la documentation disponible, et vous mettre en relation avec les bonnes personnes pour des questions plus techniques, des échanges ou des demandes d’implémentation.
Toute la documentation suivante part du principe que l’API RESPONSUM a été activée pour votre tenant.
Votre tenant key
Lorsque vous utilisez l’API RESPONSUM, vous devrez utiliser votre tenant key telle qu’elle est définie dans notre système pour chaque requête. Cette tenant key se trouve dans l’application en allant dans settings > setup > my organization et en ouvrant l’unité organisationnelle la plus élevée, car elle reflète votre tenant.
Dans les détails du tenant « Meta data » (deux flèches vers le bas en haut du panneau latéral), vous trouverez le champ « Tenant key » en lecture seule.

Cette tenant key a été définie lors de la création de votre tenant et, contrairement au nom du tenant, ne peut pas être modifiée et est unique à ce tenant spécifique.
Spécifications OpenAPI pour l’API de votre tenant
L’API RESPONSUM que vous utiliserez est générée spécifiquement pour votre tenant et inclut toutes les personnalisations (champs personnalisés, relations personnalisées, règles métier…) qui ont pu être effectuées. Par conséquent, les modèles fournis peuvent différer d’un tenant à l’autre.
Pour faciliter l’intégration, nous fournissons un fichier json de spécification conforme aux OpenAPI Specifications ; vous pouvez le charger en remplaçant la [tenant key] dans l’URL suivante par votre propre tenant key trouvée précédemment : https://api.responsum.app/v1/[tenant key]/spec.json.
Nous fournissons également une documentation visuelle basée sur ce fichier de spécification afin de permettre quelques tests simples tout en vous familiarisant avec l’API ; elle se trouve dans notre application si vous allez dans settings > integrations > API Documentation.
La première requête de cette documentation API consiste également à obtenir les spécifications OpenAPI et fait partie des seules requêtes possibles sans authentification.
Authentification et autorisation
Toutes les requêtes fonctionnelles vers l’API RESPONSUM attendent qu’un jeton API soit transmis dans la requête. Celui-ci sert à la fois à l’authentification (en vérifiant le jeton lui-même) et à l’autorisation (en vérifiant les permissions du compte utilisateur lié à ce jeton) (le lien du niveau de permission utilisateur).
Toutes les actions effectuées via l’API avec ce jeton seront également journalisées comme ayant été réalisées par l’utilisateur lié au jeton API ; ainsi, en utilisant le jeton API, vous vous faites passer pour cet utilisateur.
Création d’un jeton API
Les jetons API ne peuvent être gérés que via notre application en allant dans settings > integrations > API Tokens.
Un jeton API se compose de :
- Un nom, pour vous permettre de le reconnaître facilement dans la liste et de distinguer les jetons entre eux ;
- Une chaîne de jeton, générée pour vous et à utiliser dans chaque requête vers l’API ;
- Un niveau de permission utilisateur, lié à un compte utilisateur qui sera usurpé lors de l’utilisation de ce jeton API. Ainsi, si vous souhaitez accorder ou refuser des permissions à ce jeton API, vous le faites en accordant ou en refusant ces permissions au compte utilisateur lié ici ;
- Une date d’expiration ; si elle est définie, le jeton ne fonctionnera plus après cette date.
Une fois créé, la chaîne de jeton d’un jeton API devrait être disponible immédiatement. Si votre chaîne de jeton est compromise pour une raison quelconque, régénérer la chaîne de jeton et enregistrer le jeton API mis à jour invalidera immédiatement l’ancienne chaîne de jeton.
Transmettre le jeton API avec les requêtes
Une fois que vous disposez d’une chaîne de jeton API valide, vous pouvez la transmettre à l’API RESPONSUM en ajoutant un en-tête supplémentaire à vos requêtes Api-Token dont la valeur est votre chaîne de jeton API.
Requêtes utilitaires
UUID
Il existe diverses normes pour les Universally Unique IDentifiers actuellement utilisées, et l’API RESPONSUM devrait en accepter la plupart, car notre validation consiste à :
- Avoir une longueur d’au moins 5 caractères
- Ne contenir que les caractères suivants :
- a à z :
abcdefghijklmnopqrstuvwxyz - 0 à 9 :
0123456789 - tiret :
-
- a à z :
De plus, nous attendons que l’UUID soit unique, mais nous ne ferons qu’une vérification limitée à ce sujet : tenter de créer un nouveau modèle ou des liens avec un UUID qui existe déjà pour ce modèle ou ce lien spécifique renverra une erreur.
RESPONSUM utilise lui-même une variante de l’algorithme cuid2, modifiée pour être plus facile à reconnaître et pour correspondre à notre format préféré.
Pour vous faciliter l’utilisation d’UUID qui suivent ce format RESPONSUM, nous avons ajouté un endpoint API que vous pouvez utiliser pour générer entre 1 et 1000 UUID garantis uniques et indiscernables de ceux générés en interne par RESPONSUM.
Remplacez la tenant key et la quantité dans https://api.responsum.app/v1/[tenant key]/uuids/[amount] et effectuez une requête GET, en veillant à inclure l’en-tête Api-Token ; en valeur de retour, vous obtiendrez un tableau JSON contenant les UUID sous forme de chaînes.
Le projet d’exemple contient une opération d’exemple qui fait cela : https://github.com/RESPONSUM-BE/RESPONSUM-api-example/blob/main/src/operations/getUuids.ts
Liens
Format des liens et principe général
Les liens dans RESPONSUM sont gérés un peu différemment de la plupart des solutions courantes, dans la mesure où chaque lien est stocké comme son propre objet dans la collection de liens, en référençant les différents modèles liés entre eux, plutôt que d’avoir des références sur les modèles pointant vers d’autres modèles.
Les liens ne sont jamais mis à jour ; ils ne peuvent être que créés ou supprimés, car modifier un modèle lié est considéré comme la suppression de l’ancien lien et la création d’un nouveau lien.
Définitions de liens
Tous les liens sont basés sur différentes définitions de liens ; certaines sont codées en dur et d’autres peuvent être créées sur mesure par l’utilisateur. Lorsque vous récupérez les définitions de liens via l’endpoint GET https://api.responsum.app/v1/[tenant key]/link-definitions, vous obtenez un JSON contenant un grand objet, qui peut être vu comme un dictionnaire de toutes les définitions de liens.
Un extrait d’exemple à titre de référence :
{
"stakeholder-stakeholderContact-contacts": {
"stakeholder": {
"modelType": "stakeholder",
"oneOrMany": "one",
"isRequired": false,
"relationBehaviour": "reference-same-object"
},
"contact": {
"modelType": "stakeholder-contact",
"oneOrMany": "many",
"isRequired": false,
"relationBehaviour": "reference-same-object"
}
},
<snipped-for-size>
}
Un linkType est une clé descriptive unique pour cette définition de lien spécifique. Dans cet exemple, vous pouvez voir que chaque clé d’objet (« stakeholder-stakeholderContact-contacts ») correspond au linkType de la définition de lien.
Un role est une clé descriptive, unique au sein de la définition de lien, permettant d’identifier les différentes branches de la définition de lien. Dans ce cas, « stakeholder » et « contact » sont les deux rôles ; comme vous pouvez le constater, ils ne doivent pas nécessairement correspondre au type de modèle. Un autre exemple est celui d’un lien auto-référencé : ces rôles pourraient être « parent » et « child ».
Notez également que, même si la plupart des liens n’ont que deux branches, plus de deux sont autorisées et nous avons déjà au moins un cas de liens à trois branches.
Sous le rôle, vous avez une branch definition, qui décrit certaines propriétés de cette branche particulière :
- Le modelType décrit quels modelTypes sont autorisés ; cela peut être :
- Un seul modelType
- Un tableau de modelTypes
- La constante « all-models »
- Le oneOrMany indique s’il ne doit y avoir qu’un seul lien autorisé pour cette combinaison model type & uuid, ou s’il peut y en avoir plusieurs
- Le isRequired indique si ce lien est requis de ce côté du lien. Si true, chaque modèle du/des type(s) défini(s) dans modelType doit avoir au moins un lien de ce linkType
- Le relationBehaviour est principalement utilisé en interne pour décider quoi faire de ce lien lors de la duplication de modèles.
Objets de lien
Sur la base de la définition de lien ci-dessus, nous pouvons retrouver la même chose dans les liens réels.
Un exemple d’objet de lien pourrait ressembler à ceci :
{
"uuid": "0fc0ea83-88df-49ec-a681-1ced0a6c0683",
"type": "link",
"linkType": "stakeholder-stakeholderContact-contacts",
"links": [
{
"modelType": "stakeholder",
"modelUuid": "55092a14-4d95-4665-ac50-eb687e535222",
"role" : "stakeholder"
},
{
"modelType": "stakeholder-contact",
"modelUuid": "ad95eded-3168-4a12-968d-456bc031af7e",
"role" : "contact"
}
]
}
Les propriétés uuid et type « link » sont toujours présentes sur chaque objet afin de l’identifier de manière unique.
Le linkType correspond à l’une des définitions de liens, en l’occurrence celle de l’exemple des définitions de liens.
La propriété links est un tableau des différentes branches. Le nombre d’éléments de ce tableau correspondra toujours au nombre de rôles dans la définition de lien, car pour chaque rôle nous attendons un modèle lié.
- Le role correspond à l’un des rôles tels que définis dans la définition de lien correspondante
- Le modelType correspond à l’un des types de modèle autorisés pour la définition de lien et la définition de rôle correspondantes
- Le uuid identifie ensuite quel modèle spécifique du type de modèle donné ce lien référence
De plus, il peut également y avoir une propriété metaData qui peut contenir un objet de données libre avec des métadonnées supplémentaires sur ce lien spécifique, bien que cela soit rarement utilisé.
Requêtes directes sur les liens
La plupart du temps, vous obtiendrez les liens dans le cadre des modèles, et de la même manière vous créerez ou modifierez des liens lors de la création ou de la mise à jour de modèles.
Une propriété de lien sur un modèle, lorsqu’elle est renseignée, sera considérée comme la nouvelle liste de liens pour cette propriété, remplaçant tous les liens déjà existants pour la propriété de ce modèle. Ainsi, lorsque vous ajoutez un nouveau lien à un modèle, veillez à inclure également tous les liens existants que vous souhaitez conserver.
En plus de cela, il existe également trois endpoints pour interagir directement avec les liens.
L’endpoint GET https://api.responsum.app/v1/[tenant key]/links vous permet d’obtenir tous les liens filtrés selon plusieurs filtres :
- uuids, les uuid des objets de lien
- model-uuids, les uuid des modèles référencés dans les objets de lien
- relation-names, les linkTypes des objets de lien
Ils peuvent être fournis en paramètres de requête contenant un tableau de chaînes JSON comme valeurs.
L’endpoint POST https://api.responsum.app/v1/[tenant key]/create, bien qu’il soit principalement utilisé pour créer des modèles, accepte également des objets de lien et peut donc être utilisé pour créer de nouveaux liens.
L’endpoint DELETE https://api.responsum.app/v1/[tenant key]/link vous permet de supprimer directement un ou plusieurs liens dont vous connaissez l’uuid de l’objet de lien.
Requêtes sur les modèles
Toutes les données dans RESPONSUM sont stockées dans des modèles ; ainsi, la plupart des opérations de l’API seront effectuées sur ces modèles.
Chaque modèle doit avoir un type et un uuid, tous deux obligatoires et ne pouvant pas être modifiés après la création.
Le type est l’un de nos modèles prédéfinis, tels que « processing-activity » ou « risk ».
Définition de modèle
Cela fait référence à une définition de modèle avec tous les champs disponibles, y compris les champs personnalisés définis dans l’application. Pour type, elle contiendra le type attendu sous forme de chaîne ; veillez à utiliser exactement ces valeurs de chaîne.
Pour les champs de base, elle contiendra leur type de données et s’ils sont requis ou non.
Pour les champs de lien, elle contiendra un tableau d’objets de lien.
Lister les modèles
Pour chaque type de modèle, nous avons un endpoint GET distinct dans l’API pour obtenir tous les modèles de ce type, ou une liste filtrée.
Pour le filtrage, vous pouvez ajouter au GET url un paramètre de requête encodé en URI « param-filter » qui contient un objet JSON avec le filtre. Ce filtre a pour propriété le nom de la propriété sur laquelle vous souhaitez filtrer et pour valeur un tableau de toutes les valeurs de propriété à faire correspondre.
Par exemple, si vous souhaitez filtrer « advice » pour trouver des modèles dont le statut est « new » ou « ongoing », vous créeriez un objet de filtre json comme suit : {"status": ["new", "ongoing"]}. Ensuite, encodez-le en URI comme valeur du paramètre de requête param-filter, ce qui vous donne une requête GET comme suit : https://api.responsum.app/v1/[tenant key]/advice?param-filter=%7B%22status%22%3A%20%5B%22new%22%2C%20%22ongoing%22%5D%7D
Vous pouvez également combiner des filtres sur plusieurs propriétés en ajoutant des propriétés supplémentaires à l’objet de filtre json, comme ceci : {"status": ["new", "ongoing"], "isObsolete": [false]}. Cela renverra un tableau de modèles correspondants, ou un tableau vide si aucun modèle n’est trouvé.
Le projet d’exemple contient une opération d’exemple qui fait cela : https://github.com/RESPONSUM-BE/RESPONSUM-api-example/blob/main/src/operations/getCountriesByFilter.ts
Obtenir un modèle unique
Pour chaque type de modèle, nous avons un endpoint GET distinct dans l’API pour obtenir un modèle spécifique de ce type, sur la base de son uuid ; il suffit d’ajouter l’uuid à l’URL du type de modèle, ce qui vous donne une requête GET comme suit : https://api.responsum.app/v1/[tenant key]/advice/raou8qtt-60od-n7t5-g8el-c0sy99r0ppag
Cela renverra ce modèle unique ou une erreur 404 « no model found ».
Créer des modèles (et des liens)
Pour créer des modèles et des liens entre ces modèles, nous avons un endpoint POST générique https://api.responsum.app/v1/[tenant key]/create unique, car nous voulons permettre de créer en une seule fois un ensemble de plusieurs modèles liés et les liens entre eux, afin de réduire le risque d’ensembles partiels dus à un échec de validation ou similaire.
L’endpoint de création accepte un tableau de modèles, chacun devant avoir le type, un uuid et toutes les propriétés requises pour ce type de modèle.
Pour les propriétés de lien sur les modèles, vous pouvez également inclure un tableau d’objets de lien, dont nous prendrons l’union sur l’ensemble des modèles fournis et que nous insérerons. Cela signifie que si vous avez deux modèles qui se lient l’un à l’autre, notre API ne requiert l’objet de lien connectant ces deux modèles que sur l’un des modèles pour comprendre qu’il doit être ajouté ; toutefois, l’ajouter sur les deux modèles ne fera aucune différence.
Le projet d’exemple contient une opération d’exemple qui fait cela.
Mettre à jour des modèles (et des liens)
Pour mettre à jour des modèles et des liens entre ces modèles, nous avons un endpoint PATCH générique https://api.responsum.app/v1/[tenant key]/update unique, car nous voulons permettre de mettre à jour en une seule fois un ensemble de plusieurs modèles liés et les liens entre eux.
L’endpoint de mise à jour accepte un tableau de modèles, chacun ne devant contenir que le type, l’uuid et les champs mis à jour.
Pour les propriétés de lien sur les modèles, il s’agit à nouveau d’un tableau d’objets de lien, dont nous prendrons l’union sur l’ensemble des modèles fournis, puis nous supprimerons tous les liens qui ne font pas partie de cette union, avant d’ajouter les liens de cette union qui ne sont pas encore en base de données. Cela signifie que si vous souhaitez ajouter un lien à une propriété de modèle, vous devez également inclure les objets de lien de la propriété de modèle existante, sinon ces liens existants seront supprimés.
Le projet d’exemple contient une opération d’exemple qui fait cela.
Versioning des modèles
La plupart des modèles RESPONSUM ont le versioning activé, ce qui signifie que chaque modification apportée à ces modèles est enregistrée et que ces versions peuvent être figées et approuvées, etc.
Obtenir toutes les versions d’un modèle
Vous pouvez obtenir toutes les modifications de version pour un modèle donné avec la requête GET suivante : https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]. Cela renverra à la fois les modifications « unversioned » (Draft) et chaque version figée, avec des informations supplémentaires sur cette version, telles que le statut de version, qui l’a créée, qui l’a approuvée, etc.
Cycle de vie des versions
Modifications non versionnées
Toutes les modifications commencent comme des modifications non versionnées. Chaque fois qu’un modèle est créé ou mis à jour, nous enregistrons l’ancienne et la nouvelle valeur des propriétés modifiées. Qui et quand a effectué la modification, et quel type d’opération il s’agissait.
La liste des opérations comporte des valeurs courantes telles que ‘create’, ‘update’, ‘delete’, ‘merge’, ‘import’, ‘history-restoration’ et ‘update-link’, mais peut aussi contenir des valeurs spéciales telles que ‘V2-create’ pour notre import legacy, et de nouvelles valeurs peuvent être ajoutées à tout moment selon les évolutions futures.
Figer
À tout moment, les modifications d’un modèle peuvent être figées via POST https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/freeze, ce qui créera une nouvelle version avec le reviewStatus ‘frozen’ et inclura toutes les modifications non versionnées qui existaient. S’il n’y avait aucune modification non versionnée, aucune nouvelle version ne sera créée.
Vous pouvez également fournir un nom de version lors du gel, mais si aucun n’est fourni, il sera calculé sur la base des versions existantes.
À ce stade, certaines personnes disposant des bonnes permissions peuvent déjà approuver ou rejeter cette version, mais le plus important est que toute nouvelle modification sera ajoutée comme modification non versionnée, tandis que les modifications de cette version ne changeront jamais.
Demander une approbation
Pour faire approuver ou rejeter une version, vous pouvez demander à des personnes spécifiques de la relire. Pour cela, vous pouvez faire un PUT https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/request-approval avec un uuid de version et un uuid d’« accountable user ». Cela déclenchera des notifications pour que cette personne examine cette version et l’approuve ou la rejette.
Approuver ou rejeter
Vous pouvez également approuver ou rejeter des versions via l’API si l’utilisateur lié à votre jeton dispose de permissions suffisantes.
Cela peut se faire via les deux endpoints PUT https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/approve ou https://api.responsum.app/v1/[tenant key]/version/[model type]/[model uuid]/reject, nécessitant à nouveau l’uuid de la version que vous souhaitez approuver ou rejeter.
Webhooks
Parfois, vous souhaitez également être informé de la création ou de la mise à jour de modèles ; pour cela, nous avons des webhooks que vous pouvez configurer en allant dans settings > integrations > webhooks.
Pour faciliter l’utilisation, les webhooks peuvent être activés ou désactivés ; seuls les webhooks activés déclencheront des appels.
Le nom sert uniquement à distinguer les webhooks.
L’URL fournie sera appelée avec les en-têtes fournis ; il s’agira d’une requête POST contenant un corps json avec changeAction, modelType et uuids (un tableau d’uuids).
Vous pouvez sélectionner parmi les actions de changement suivantes ; seules celles sélectionnées déclencheront l’appel du webhook :
- ‘link-deleted’ : lorsqu’un lien est supprimé d’une ou plusieurs propriétés
- ‘link-created’ : lorsqu’un lien est ajouté à une ou plusieurs propriétés
- ‘item-deleted’ : lorsque l’élément est supprimé
- ‘item-meta-data-updated’ : lorsque des propriétés calculées sont mises à jour, par ex. last updated by, review status, etc.
- ‘item-base-data-updated’ : lorsque les propriétés de base sont mises à jour, par ex. name, isObsolete, etc.
- ‘item-created’ : lorsque l’élément est créé
Vous pouvez sélectionner le sous-module pour lequel le webhook doit se déclencher ; cela peut être aussi précis qu’un seul type de modèle ou aussi large que tous les modèles de l’application.
Selon notre logique interne, vous pourriez recevoir plusieurs appels de webhook pour le même model type & uuid à peu d’intervalle, après l’enregistrement par un utilisateur. Par exemple, ajouter un lien et définir une propriété déclenchera un appel ‘item-base-data-updated’, ‘item-meta-data-updated’ et ‘link-created’.
Application d’exemple
https://github.com/RESPONSUM-BE/RESPONSUM-api-example
Consultez le readme pour démarrer ; une fois l’application lancée et http://localhost:3000 ouvert, vous devriez voir quelque chose comme ceci :

Au fur et à mesure que vous effectuez les différentes opérations, vous verrez un journal des opérations sur le côté droit de la page.
Vous pouvez également retrouver toutes ces opérations dans le dossier src\operations\