5.3Webservices, API REST & échanges
L'essentiel en 30 secondes
- Les API REST sont le standard d'échange : Yacine consomme l'API d'un fournisseur pour les prix et expose un service pour les commandes du site e-commerce, en JSON sur HTTP.
- Le vocabulaire REST se maîtrise : URL, méthodes GET/POST/PUT/DELETE, jeton d'authentification jamais codé en dur et codes de retour traités systématiquement.
- La robustesse prime : ne jamais faire confiance aux données reçues, prévoir délais, reprises, file d'attente, idempotence et journalisation des échanges.
Mini-cas filé — Yacine branche sa gestion sur les API partenaires
Yacine développe l'application de gestion d'une PME de négoce de matériel électrique à Oran. Pour éviter de ressaisir les prix, il interroge l'API REST d'un fournisseur : un GET renvoie le prix et le stock d'un article au format JSON. Pour le site e-commerce du distributeur, il expose lui-même une API qui reçoit les commandes en POST et renvoie leur statut. Le jeton d'authentification n'est pas écrit dans le code : il est lu depuis un paramètre sécurisé. Chaque réponse est validée avant enregistrement, car un prix à zéro ou un code article inconnu ne doit jamais entrer dans la base. Quand le fournisseur est indisponible, la demande part dans une file d'attente et sera rejouée avec un identifiant unique pour éviter les doublons. Yacine journalise chaque appel : date, sens, service, code de retour et données résumées.
Cas autonome de cette section : il revient dans le cours, le schéma, le code et le défi 48h de la section 5.3.
1. Consommer et exposer
Une application de gestion vit rarement isolée : elle échange avec la comptabilité, un ERP, un site e-commerce, une banque ou un fournisseur. Les webservices et API REST sont le standard moderne. Consommer une API consiste à appeler un service distant pour obtenir ou envoyer des données ; exposer une API consiste à publier la sienne pour que d'autres applications l'appellent. Les échanges se font le plus souvent en JSON sur HTTP. Les fichiers d'échange (CSV, XML, JSON, Excel) restent utiles pour les imports et exports par lot, et l'accès direct à une autre base existe encore, mais l'API REST est le mode privilégié pour le temps réel.
2. Le vocabulaire REST
Pour appeler une API, Yacine identifie l'URL du service et la méthode : GET pour lire, POST pour créer, PUT pour modifier, DELETE pour supprimer. L'authentification repose souvent sur une clé ou un jeton : ces secrets ne doivent jamais être écrits en dur dans le code ni exposés côté client. Le format des données (JSON le plus souvent) doit être analysé et converti en objets métier. Enfin, les codes de retour indiquent le succès, une erreur d'authentification, une ressource introuvable ou une erreur serveur : ils se traitent systématiquement. Un code 200 ne garantit pas que les données sont correctes, et un code 500 n'est pas une raison d'abandonner sans trace.
3. Robustesse et traçabilité
Un service distant sera indisponible, lent ou incohérent un jour. Yacine part de ce principe et prévoit un délai d'attente, des reprises espacées, une file d'attente pour ne rien perdre et un traitement asynchrone pour ne pas bloquer l'utilisateur. L'idempotence évite les doublons lorsqu'un envoi est répété : un identifiant unique d'opération permet au serveur de reconnaître une demande déjà traitée. Toutes les données reçues sont validées avant enregistrement. Enfin, les échanges sont journalisés : date, sens, service, code de retour, données résumées et identifiant métier. C'est la seule preuve exploitable en cas de litige avec un partenaire, et le meilleur outil pour diagnostiquer une panne intermittente.
🔎 Exemple concret — 🔎 Exemple concret — Consommer l'API prix fournisseur
Yacine récupère un prix et refuse toute valeur incohérente :
// Consommation de l'API prix fournisseur
sURL est une chaîne = "https://api.fournisseur.dz/articles/" + SAI_CodeArticle
sReponse est une chaîne = RESTEnvoie(sURL, "GET", gsJetonFournisseur)
SI sReponse = "" ALORS
Erreur("Service fournisseur indisponible")
RENVOYER Faux
FIN
oArticle est un dynamic ArticleAPI
JSONVersObjet(sReponse, oArticle)
SI oArticle.PrixHT <= 0 ALORS
Erreur("Prix reçu invalide")
RENVOYER Faux
FIN
RENVOYER VraiRésultat : aucun prix nul ou négatif n'entre dans la base de Yacine.
Réflexe : le jeton vient d'un paramètre sécurisé, jamais du code source.
Vocabulaire de la section
- API REST
- Service web exposant des ressources via des URL et des méthodes HTTP, souvent en JSON.
Exemple simple : Yacine interroge l'API du fournisseur pour les prix et les stocks.
Ce que ce n'est pas : recopier à la main les tarifs dans l'application.
Réflexe : API REST = échange standardisé en temps réel.
- Méthodes HTTP
- Verbes du protocole HTTP : GET (lire), POST (créer), PUT (modifier), DELETE (supprimer).
Exemple simple : Yacine utilise GET pour consulter et POST pour recevoir une commande.
Ce que ce n'est pas : tout faire avec un seul verbe sans distinguer l'action.
Réflexe : la méthode décrit l'intention de l'échange.
- Jeton d'API
- Secret d'authentification présenté à chaque appel pour prouver l'identité de l'application.
Exemple simple : Yacine lit son jeton dans un paramètre sécurisé.
Ce que ce n'est pas : écrire le jeton en clair dans le code ou dans une page.
Réflexe : un secret ne se code jamais en dur.
- Idempotence
- Propriété d'un échange qui, répété avec le même identifiant, ne crée pas de doublon.
Exemple simple : Yacine joint un identifiant d'opération unique à chaque commande.
Ce que ce n'est pas : renvoyer la même commande après une coupure réseau.
Réflexe : idempotence = reprise sans doublon.
- Journal d'échanges
- Trace horodatée des appels : sens, service, données résumées, code de retour et identifiant métier.
Exemple simple : Yacine consulte le journal pour diagnostiquer un prix refusé.
Ce que ce n'est pas : n'enregistrer aucun échange et supposer que tout va bien.
Réflexe : le journal est la preuve et l'outil de diagnostic.
En pratique — En pratique — Échanger avec d'autres systèmes
- Identifiez le mode adapté : API REST pour le temps réel, fichiers CSV/XML/JSON pour les lots, accès direct à une autre base en dernier recours.
- Pour consommer une API, repérez l'URL, la méthode (GET/POST/PUT/DELETE), l'authentification et le format JSON, sans jamais coder le secret en dur.
- Traitez systématiquement les codes de retour et les pannes (service indisponible, délai dépassé) avec reprise, file d'attente et idempotence.
- Validez toutes les données reçues, journalisez les échanges et vérifiez vos obligations sur les données personnelles transmises.
Script pas-à-pas — journaliser un échange (10 min)
Yacine trace chaque réponse du fournisseur pour pouvoir diagnostiquer et prouver.
On journalise un résumé si les données sont volumineuses, mais toujours l'identifiant métier qui relie l'échange à la commande.
Modèle copier-coller — ma fiche d'échange API
// Fiche d'échange — Yacine
// Service : API fournisseur matériel électrique
// URL : https://api.fournisseur.dz/articles/{code}
// Méthode : GET
// Authentification : jeton lu dans ParametreSecurise("API_FOURNISSEUR")
// Format : JSON (ArticleAPI)
// Codes traités : 200, 401, 404, 429, 500
// Robustesse : délai 10 s, 3 reprises espacées, file d'attente
// Idempotence : NumeroOperation unique
// Journal : date, sens, service, code, données résuméesPrix fournisseur
Yacine consomme l'API d'un fournisseur pour actualiser les prix et les stocks.
Commande e-commerce
Yacine expose une API POST qui reçoit les commandes du site partenaire.
Export comptable
Yacine produit un fichier CSV pour la comptabilité lorsque l'API n'est pas disponible.
Reprise après panne
Yacine met les envois en file d'attente et les rejoue avec un identifiant unique.
✓ Bonnes pratiques
- Protéger les jetons et clés d'API hors du code source.
- Valider toutes les données reçues avant enregistrement.
- Prévoir reprises, file d'attente et journal dès le premier échange.
✗ Pièges fréquents
- Coder un secret en dur dans l'application ou une page.
- Faire confiance au code 200 sans vérifier les données.
- Renvoyer une demande sans identifiant d'opération et créer un doublon.
Points clés à retenir
- Les API REST échangent en JSON sur HTTP, en consommation comme en exposition.
- URL, méthodes, authentification et codes de retour forment le vocabulaire REST.
- Les secrets ne sont jamais codés en dur et les données reçues sont validées.
- Délais, reprises, file d'attente, idempotence et journal rendent les échanges robustes.
Défi 48h — appliquez demain
Comme Yacine, appelez une API publique en GET depuis un petit projet WinDev, analysez le JSON et validez un champ avant de l'enregistrer. Ajoutez un journal d'échange (date, service, code de retour, données résumées) et simulez une panne en coupant le réseau. Vérifiez que la demande part en file d'attente et qu'un renvoi ne crée pas de doublon.
- Je peux expliquer la différence entre consommer et exposer une API.
- Je sais nommer les méthodes HTTP et protéger un jeton.
- Je sais rendre un échange robuste et journalisé.
Questions fréquentes
Pourquoi faut-il journaliser les échanges avec des systèmes externes ?
Parce qu'en cas de problème, le journal est la seule preuve de ce qui a été envoyé et reçu, et à quel moment. Il permet de diagnostiquer une donnée fausse, une panne intermittente ou un changement non annoncé chez le partenaire. Il sert aussi à reprendre après incident en sachant précisément ce qui est passé, et à répondre à un litige ou à un audit. Yacine journalise la date, le sens, le service, le code de retour, un résumé des données et l'identifiant métier (numéro de commande ou de facture). Sans cet identifiant, le journal est difficile à relier à l'opération réelle.
Comment rendre robustes des échanges qui dépendent d'un service externe ?
En partant du principe que le service sera un jour indisponible, lent ou incohérent. Il faut un délai d'attente pour ne pas bloquer indéfiniment, des reprises espacées et limitées, une file d'attente pour conserver les demandes non envoyées, un traitement asynchrone pour ne pas bloquer l'utilisateur, et un identifiant d'opération unique pour rendre l'envoi idempotent. Toutes les réponses sont validées avant enregistrement, et chaque échange est journalisé. Yacine prévoit aussi une information claire de l'utilisateur lorsque l'échange est différé.
Que faire des données reçues d'une API fournisseur avant de les enregistrer ?