6 manières d’utiliser les APIs pour accélérer votre intégration

Published in

Sandbox Produit

8 min readSep 27, 2023

Les interfaces API sont la passerelle pour tout logiciel SaaS qui souhaite s’insérer dans un écosystème de solutions techniques et données tiers riches pour offrir une expérience d’interopérabilité à leurs utilisateurs.

L’objectif de cet article est de décrire les usages des API à différents phases d’une intégration à destination des équipes de développement. Elles permettent notamment de :

💫Explorer de nouvelles opportunités d’intégration

🧭Dé-risquer le développement d’une nouvelle intégration

🧩Anticiper l’intégration d’un système tiers

🚦Anticiper la recette d’une fonctionnalité

📞Faciliter le travail du support technique

⚙️Réaliser des opérations avancées

Nous prendrons des exemples du secteur du e-commerce et d’outils API pour illustrer nos propos.

💫 1. Explorer de nouvelles opportunités d’intégration

L’écosystème des applications tiers est riche et chaque acteur a un vocabulaire et un fonctionnement qui lui sont propres. La documentation API décrit généralement l’ossature pour les possibilités d’intégration. Elle permet de :

Échanger de manière cadrée et structurée entre les différents interlocuteurs
Comprendre le système tiers rapidement à travers sa structure et ses flux de données
Imaginer rapidement des cas d’usage métier possibles

On retrouve par exemple dans l’e-commerce, les mêmes objets comme :

📦Les produits : le catalogue, les types de produit, le stock, les méta-descriptions
🛒Les commandes : le panier, le paiement, la livraison, la facturation
👤Les acheteurs : les informations personnelles, les préférences, les activités
🏪Les enseignes : le paramétrage, l‘affichage du site, les gérants

Les systèmes tiers vont généralement proposer des extensions à l’un ou plusieurs de ces objets :

🔽En entrée : on récupère de la donnée ou on reçoit des notifications du système tiers
🔼En sortie : on envoie de la donné ou on envoit des notifications au système tiers

Pour évaluer une opportunité d’intégration, il est nécessaire d’identifier les flux et les structures d’objets impactés en interne.

🧭2. Dé-risquer le développement d’une nouvelle intégration

Une fois l’opportunité identifiée, il est nécessaire d’évaluer la faisabilité de l’intégration. Pour cela, la mise à disposition d’un environnement API de test permet d’accélérer le développement de l’intégration :

Valider les capacités d’intégration du système tiers
Prototyper et définir le périmètre d’intégration
Échanger de manière structurée avec l’intégrateur ou le développeur sur les résultats attendus

La plupart du temps, il s’agit dans une intégration, de faire correspondre les données entre les deux systèmes. Cependant il n’est pas rare qu’il y ait des manquements et que des évolutions des APIs soient nécessaires d’où l’importance d’étudier en amont.

Beaucoup de systèmes tiers proposent des champs extensibles custom fields ou metadata pour permettre d’ajouter des informations externes qui n’ont pas été prévues.

Soit l’exemple d’une commande avec les propriétés suivantes :

{
  "order_id": "12345",
  "customer_id": "67890",
  "order_date": "2023-09-27T14:30:00Z",
  "items": [
    {
      "product_id": "A001",
      "quantity": 2,
      "unit_price": 25.99
    },
    {
      "product_id": "B002",
      "quantity": 3,
      "unit_price": 12.49
    }
  ],
  "shipping_address": {
    "street": "123 Rue Principale",
    "city": "Exempleville",
    "state": "CA",
    "postal_code": "12345"
  },
  "total_price": 94.95,
  "payment_method": "Carte de crédit",
  "metadata": {
    "notes": "Le client a demandé une livraison accélérée.",
    "promocode": "ECONO10",
    "source": "Site Web",
    "shipping_method": "Express",
    "gift_wrap": true
  }
}

order_id, customer_id et order_date représentent les informations de base de la commande.
items contient une liste des produits de la commande, avec des détails pour chaque article.
shipping_address inclut l'adresse où la commande doit être livrée.
total_price représente le coût total de la commande.
payment_method spécifie la méthode de paiement.
metadata contient des champs de métadonnées supplémentaires, tels que des notes de commande, un code promotionnel, la source de la commande (par exemple, le site Web), la méthode de livraison et la demande d'emballage cadeau. Ces champs de métadonnées supplémentaires peuvent être personnalisés pour stocker des informations supplémentaires pertinentes pour la commande.

🧩 3. Anticiper l‘intégration d’un système tiers

Parfois, l’environnement de test n’est pas disponible ou les informations manquent dans la documentation ou les évolutions APIs demandées ne sont pas encore prêtes.

Plusieurs leviers sont disponibles pour avancer sur l‘intégration :

En l’absence de documentation API exhaustive, tester les requêtes pour vérifier la couverture fonctionnelle
En l’absence de documentation webhook, créer un endpoint avec Pipedream par exemple, pour vérifier les réponses

En l’absence de webhook de test, simuler une notification envoyée par le système tiers sur notre application avec Postman
En l’absence d’environnement API de test, simuler un serveur de mock avec des requêtes et des réponses d’exemple

Imaginons que nous devons développer une page de statut de commande et qu’un système tiers est censé envoyer ces notifications.

En l’absence d’environnement API de test, nous pouvons imaginer partir de la documentation pour construire les réponses API attendues et poursuivre le développement de notre page.

{
  "customer_id": "98765",
  "order_id": "12345",
  "status_code": "PLC",
  "status_message": "Order Placed",
  "cancellation_reason": "",
  "timestamp": "2023-09-27T10:00:00Z"
}

{
  "customer_id": "98765",
  "order_id": "12345",
  "status_code": "SHP",
  "status_message": "Order Shipped",
  "cancellation_reason": "",
  "timestamp": "2023-09-28T15:30:00Z"
}

{
  "customer_id": "98765",
  "order_id": "12345",
  "status_code": "DLV",
  "status_message": "Order Delivered",
  "cancellation_reason": "",
  "timestamp": "2023-10-02T18:15:00Z"
}

{
  "customer_id": "98765",
  "order_id": "12345",
  "status_code": "CXL",
  "status_message": "Order Cancelled",
  "cancellation_reason": "Customer Request",
  "timestamp": "2023-09-29T09:45:00Z"
}

L’utilisation de ChatGPT permet avec un peu d’adaptation, de générer assez rapidement les requêtes d’exemple.

🚦4. Anticiper la recette d’une fonctionnalité

Les spécifications ne sont généralement pas suffisament exhaustives au moment où elles ont été pensées et les développeurs ne sont pas forcément au courant de tous les cas à la marge.

L’utilisation d’un outil de test API comme Postman en amont permet d’accélérer grandement la recette :

Vérifier le fonctionnement attendu sans attendre la fin du développement de l’interface
Générer les cas métiers complexes où la saisie dans l’interface est fastidieuse
S’assurer de l’alignement sur les cas de test au sein de l’équipe technique : développement front, back et QA

Supposons le cas d’une création de commande, nous avons parfois besoin de tester des cas différents :

Des produits différents : formules, suppléments
Des montants différents : quantité, tva, prix
Des modes de distribution différents : sur place, en livraison, à emporter
Avec des codes de réduction
…

Comme il est important de ne pas mélanger les cas de test, les traiter un par un est une bonne pratique. Ci-joint 3 exemples de requêtes de commande différentes :

1/ Commande en retrait sur place avec une formule et une réduction

{
  "order_id": "24680",
  "customer_id": "13579",
  "order_items": [
    {
      "product_id": "F001",
      "product_name": "Family Meal",
      "quantity": 1,
      "unit_price": 24.99,
      "vat": 4.07,
      "components": [
        {
          "product_id": "P123",
          "product_name": "Special Pizza",
          "quantity": 1,
          "unit_price": 12.99,
          "vat": 2.10
        },
        {
          "product_id": "S456",
          "product_name": "Extra Cheese (Supplement)",
          "quantity": 1,
          "unit_price": 2.50,
          "vat": 0.40
        }
      ]
    },
    {
      "product_id": "S789",
      "product_name": "Smoothie",
      "quantity": 3,
      "unit_price": 3.49,
      "vat": 0.57
    }
  ],
  "discount": 5.00,
  "discount_code": "FAMILYDEAL",
  "order_type": "Click and Collect",
  "vat": 6.07,
  "total_amount": 28.95,
  "status_code": "PLC",
  "status_message": "Order Placed",
  "ordered_date": "2023-09-28T10:15:00Z",
  "delivery_date": null
}

2/ Commande à table avec des produits simples

{
  "order_id": "98765",
  "customer_id": "54321",
  "order_items": [
    {
      "product_id": "P789",
      "product_name": "Burger",
      "quantity": 2,
      "unit_price": 7.99,
      "vat": 1.29
    },
    {
      "product_id": "F101",
      "product_name": "French Fries",
      "quantity": 1,
      "unit_price": 3.49,
      "vat": 0.57
    },
    {
      "product_id": "D222",
      "product_name": "Soda",
      "quantity": 3,
      "unit_price": 1.99,
      "vat": 0.32
    }
  ],
  "discount": 0.00,
  "discount_code": null,
  "order_type": "Eat at Table",
  "table_number": 8,
  "vat": 2.18,
  "total_amount": 27.18,
  "status_code": "PLC",
  "status_message": "Order Placed",
  "ordered_date": "2023-09-27T19:30:00Z",
  "delivery_date": null
}

3/ Commande en livraison avec des produits et des suppléments

{
  "order_id": "54321",
  "customer_id": "98765",
  "order_items": [
    {
      "product_id": "P123",
      "product_name": "Special Pizza",
      "quantity": 1,
      "unit_price": 12.99,
      "vat": 2.10
    },
    {
      "product_id": "S456",
      "product_name": "Extra Cheese (Supplement)",
      "quantity": 1,
      "unit_price": 2.50,
      "vat": 0.40
    }
  ],
  "discount": 0.00,
  "discount_code": null,
  "order_type": "Delivery",
  "delivery_fee": 3.99,
  "vat": 2.75,
  "total_amount": 26.74,
  "status_code": "PLC",
  "status_message": "Order Placed",
  "ordered_date": "2023-09-27T13:45:00Z",
  "delivery_date": "2023-09-28T15:00:00Z"
}

📞5. Faciliter le travail du support technique

Une fois l’intégration envoyée en production, des bugs peuvent vite arriver avec l’incertitude sur à qui revient la responsabilité de corriger entre son propre application ou celui du système.

Pour cela, l’analyse des réponses APIs permet de :

Vérifier si le bug vient du système tiers, du front ou du back
S’assurer de l’exactitude de l‘information reçue du système tiers en temps réel
Approfondir l’investigation en regardant les données ou erreurs techniques non disponibles dans les interfaces

L’utilisation d’un outil comme Chrome Dev Tools permet d’investiguer le détail des réponses API qui arrivent au niveau de l’interface utilisateur.

Soit l’exemple d’un bug sur le montant de la TVA remonté dans l’affichage de la facture de l’interface utilisateur.

Si on envoie une requête API :

À notre système et au système tiers, et que la TVA indiquée est correcte✅, alors le problème vient de l’interface
À notre système et que la TVA est fausse ❌, au système tiers que la TVA est correcte ✅, alors le problème vient de notre système de calcul
À notre système et au système tiers, et que la TVA indiquée est fausse ❌ alors le problème vient de la donnée fournie par le partenaire

⚙️6. Réaliser des opérations avancées

Parfois, il arrive à la demande du client ou dans le cadre d’une investigation résolution de bug, qu’on ait à réaliser des opérations API en masse et ponctuelles qui ne sont pas disponibles via les interfaces.

Un outil API permet de :

Dérouler un processus métier automatiquement et vérifier le résultat à chaque étape
Faire des ajouts, des modifications ou des vérifications ponctuels ou en masse quand cela n’est pas possible par l’interface
Récupérer la donnée de manière structurée et en masse en l’absence des fonctionnalités d’export ou d’analytics

Avec Postman, il est possible :

d‘enchaîner des requêtes API automatiqument en utilisant des scripts
de lancer des requêtes personnalisées à partir de données qui viennent d’une feuille de calcul

de visualiser sous forme de tableau ou de graphique les éléments d’une liste dans une réponse API