Présentation des intégrations d’API REST

Les clients peuvent choisir de fournir des données de base à Chrome River via des flux de données ou via nos services Web API REST. Une API Web est accessible par Internet et est exécutée sur un système à distance qui héberge les services demandés. Ces services offrent de la flexibilité en permettant à votre organisation de transmettre des données partielles plutôt qu’un fichier de flux contenant toutes les lignes de données, quel que soit le nombre de mises à jour requises.

En outre, si une partie d’un appel d’API échoue, vous en serez immédiatement informé au moyen d’un message d’erreur. Seule la partie touchée de la transmission échouera, les autres parties seront transmises.

Bien que les spécifications techniques de chaque API se trouvent dans la boîte à outils de mise en œuvre de Chrome River, cet article vous aidera à comprendre comment fonctionnent nos intégrations d’API REST et vous indiquera les bonnes pratiques pour les concevoir.

API REST versus flux de données

Le choix entre l’utilisation d’API REST et de fichiers plats pour les intégrations de données dépend des exigences d’intégration de votre organisation et des caractéristiques des données échangées. Chaque option a ses avantages et ses inconvénients. Voici quelques raisons pour lesquelles vous pourriez envisager d’utiliser une API REST au lieu d’envoyer un flux de données :

1. Accès aux données en temps réel

  • API REST : elles fournissent un accès en temps réel aux données. Vous pouvez envoyer les informations les plus récentes lorsque vous en avez besoin.
  • Flux de données : ils représentent généralement un instantané des données à un moment spécifique. Vous devez régénérer ou mettre à jour les fichiers pour obtenir les dernières informations.

2. Facilité d’intégration

  • API REST : elles sont conçues pour une intégration facile. Elles utilisent des méthodes HTTP standard quel que soit le langage, ce qui les rend accessibles à un large éventail de langages de programmation.
  • Flux de données : ils peuvent nécessiter une logique d’analyse personnalisée et le processus d’intégration peut être plus complexe, en particulier si la structure des données change fréquemment.

3. Évolutivité

  • API REST : elles peuvent traiter de plus gros volumes de données en envoyant des requêtes incrémentielles jusqu’à ce que toutes les mises à jour soient terminées. Il s’agit d’une approche plus évolutive.
  • Flux de données : cette option peut devenir inconfortable à mesure que le volume de données augmente. La gestion de fichiers volumineux, en particulier dans les environnements distribués, peut se révéler complexe.

4. Sécurité

  • API REST : elles proposent des mécanismes d’authentification et d’autorisation. Vous pouvez contrôler qui accède aux données et quelles actions ces personnes peuvent effectuer.
  • Flux de données : ils peuvent exiger des mesures de sécurité supplémentaires telles que le chiffrement et des protocoles de transfert de fichiers sécurisés pour protéger les informations sensibles.

5. Versions et évolution

  • API REST : elles permettent la gestion des versions, ce qui facilite la gestion des modifications de la structure de données au fil du temps sans interrompre les intégrations existantes.  
  • Flux de données : les modifications apportées à la structure peuvent nécessiter une coordination et une communication manuelles pour garantir la compatibilité avec les systèmes existants.

6. Granularité des données

  • API REST : elles vous permettent d’envoyer et de recevoir des éléments de données spécifiques tout en offrant un contrôle plus précis sur les informations que vous récupérez. Cela est particulièrement avantageux lorsqu’il peut y avoir plus d’une source de données.
  • Flux de données : ils contiennent souvent toutes les données, ce qui peut donner lieu à une récupération et un traitement inutiles des informations.

7. Gestion des erreurs et journalisation

  • API REST : elles offrent une gestion des erreurs standardisée, des codes d’état et des mécanismes de journalisation, ce qui facilite la résolution des problèmes.
  • Flux de données : la gestion des erreurs nécessite une surveillance manuelle, car les journaux d’erreurs sont envoyés par e-mail, et les problèmes de débogage peuvent s’avérer plus complexes à résoudre.

8. Notifications en temps réel

  • API REST : l’activation des notifications ou des rappels en temps réel permet à votre système d’être informé instantanément des problèmes pendant la transmission.
  • Flux de données : généralement, vous devez interroger le système ou vérifier régulièrement les mises à jour, ce qui n’est pas toujours aussi réactif ou efficace.

FAQ

Y a-t-il des pare-feu à ouvrir du côté de Chrome River ? 

Non.

Est-il possible de combiner les flux de données et les API REST ?

Oui. Par exemple, les données Personne peuvent être envoyées via SFTP et les données Allocation peuvent être envoyées via l’API REST. Cependant, vous ne pouvez pas envoyer de données en utilisant les deux méthodes pour un seul type, comme Entité et Personne.

Premiers pas avec les API REST

Avant que votre organisation puisse commencer à utiliser les API REST, un membre de l’équipe de mise en œuvre de Chrome River doit activer les ressources que vous souhaitez utiliser et vous fournir votre code client. (Si votre organisation n’est plus dans la phase de mise en œuvre, créez un dossier via le portail du service d’assistance pour en faire la demande).

Ensuite, l’un des administrateurs de votre organisation doit générer une clé API à partir de l’écran d’administration Gestion des clés API dans Chrome River. Voir Écran d’administration Gestion des clés API pour plus de détails.

La combinaison de la clé API et de votre code client vous permet de lancer des requêtes d’API REST à Chrome River.  

Assurez-vous que vous utilisez la bonne combinaison d’environnement et de clé API. Si votre organisation dispose d’un environnement QA/UAT et que vous effectuez des tests dans cet environnement inférieur, assurez-vous d’utiliser l’URL et la clé API correctes générées dans cet environnement. Une clé API de production ne fonctionnera pas dans un environnement QA, et une clé API d’environnement QA ne fonctionnera pas dans un environnement Production.
curl --location --request GET 'https://service.chromeriver.com/v4/persons/10000000' \
--header 'x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--header 'customer-code: XXXX' \
--header 'chain-id: 550e8400-e29b-41d4-a716-446655440000'

URL de base

  • Production : service.chromeriver.com/
  • QA/UAT : qa-service.chromeriver.com/

Spécifications des API REST

Pour afficher les spécifications techniques de chaque API Chrome River, consultez la boîte à outils de mise en œuvre.

Chaque API possède une page Swagger que votre équipe technique peut utiliser pour mieux comprendre la structure des requêtes. Il faut les utiliser conjointement avec le document Spécification d’intégration des fichiers mappé au cours de vos ateliers préalables avec notre équipe de mise en œuvre. Votre contact au sein de l’équipe de mise en œuvre de Chrome River ou le service d’assistance peut également fournir des exemples de requêtes cURL.

RAIO - Sample Image.png

Bonnes pratiques de conception

Les bonnes pratiques suivantes vous aideront à concevoir vos requêtes API et à consigner les erreurs pour un dépannage efficace.

chain-id

Il faut toujours inclure un identifiant de chaîne unique chain-id dans vos requêtes API envoyées à Chrome River. Nous recommandons un GUID (Globally Unique ID ou identifiant global unique). Cela aidera l’assistance technique de Chrome River à résoudre les problèmes lorsque vous devez enquêter sur une erreur.

--header 'chain-id: 550e8400-e29b-41d4-a716-446655440000'

Quand un champ doit-il être inclus dans une requête ?

Reportez-vous à votre document Spécification d’intégration de fichiers pour mieux comprendre quelles données doivent être incluses dans des champs spécifiques pour votre organisation. Dans la plupart des cas, si vous n’utilisez pas ce champ ou ce tableau, il est recommandé de l’exclure de la requête.  

  • Par exemple, si vous travaillez sur l’API Personne et que vous n’utilisez pas le champ UDF, n’incluez pas de tableau vide car cela entraînera une erreur « 400 Bad Request ».
   "udas": [
       {
           "name": "",
           "value": ""
       },

Journalisation/Gestion des erreurs

Lorsque vous envoyez et recevez des données depuis des API Chrome River, il est essentiel de vous concentrer sur les stratégies de journalisation qui enregistrent les détails de ces interactions pour un dépannage et une surveillance efficaces.

Vous trouverez ci-dessous quelques points spécifiques à prendre en compte pour la gestion des journaux dans ce contexte.

  • Charges utiles de requête et de réponse : enregistrez l’intégralité de la charge utile de la réponse (données sortantes) et la charge utile de la réponse (données entrantes) pour chaque interaction d’API. Ces données sont précieuses pour diagnostiquer les problèmes liés au format des données, au contenu ou aux valeurs inattendues.
  • Codes d’état HTTP : enregistrez les codes d’état HTTP renvoyés par l’API Chrome River. Ceci permet d’obtenir un aperçu immédiat de la réussite ou de l’échec de chaque appel d’API.
  • En-têtes de requête et de réponse : incluez des en-têtes pertinents dans vos journaux, en particulier ceux liés à l’authentification, au type de contenu et tout en-tête personnalisé requis par l’API Chrome River.
  • Horodatages et durées : incluez des horodatages dans vos journaux pour suivre la chronologie des requêtes et des réponses API. En outre, enregistrez la durée de chaque appel API pour identifier les goulots d’étranglement de performances.
  • Erreurs de journalisation et exceptions : enregistrez des informations détaillées sur les erreurs ou les exceptions qui se produisent pendant les interactions avec l’API. Il convient d’inclure des traces de pile et des informations contextuelles pour faciliter le débogage.
  • Mécanisme de nouvelle tentative : si votre application met en œuvre un mécanisme de nouvelle tentative pour les requêtes API qui ont échoué, consignez les détails des nouvelles tentatives, y compris le nombre de tentatives et les stratégies de sauvegarde utilisées.  Assurez-vous que le nombre de nouvelles tentatives soit limité, généralement entre 1 et 5. Pour éviter l’interruption de votre accès à l’API, n’autorisez pas la nouvelle tentative continue.
  • Transformation des données : si votre application transforme ou mappe des données avant l’envoi ou après la réception depuis l’API Chrome River, consignez les détails pertinents pour aider à comprendre toute différence entre les données.
  • Alertes et surveillance : vous pouvez mettre en œuvre des alertes basées sur les journaux pour recevoir des notifications relatives aux problèmes critiques. Utilisez les outils ou services de surveillance des journaux pour détecter les schémas et les anomalies.
  • Informations contextuelles : ajoutez ces informations spécifiques au contexte en tant qu’objectif ou contexte de l’appel API pour une meilleure compréhension des journaux sans avoir besoin de se référer au code.
  • Points d’intégration : enregistrez clairement les parties de votre application responsables des appels API. Cela permet d’identifier la source des problèmes dans un système distribué.

En prêtant attention à ces points en particulier, vous pouvez élaborer une stratégie de journalisation complète qui facilite la surveillance, le dépannage et l’optimisation efficaces de vos interactions avec les API Chrome River. Assurez-vous d’examiner et de mettre à jour régulièrement votre stratégie de journalisation à mesure que votre intégration évolue.

Cet article vous a-t-il été utile ?