En rapprochant plusieurs écosystèmes chez HLC, je vois pourquoi un accès direct à la base est tentant. Il est rapide au début et lie le consommateur aux tables internes pour longtemps. Une API introduit un contrat : ressource, schéma, règles, erreurs et évolution indépendantes du stockage.

Pour GET /produits/471, le serveur authentifie le client, autorise le produit, lit la source, transforme vers une représentation et retourne statut, version et cache. Le client ne devrait pas connaître le nom des tables AX ni la façon dont le prix est calculé.

Concevoir une écriture qui résiste au réseau

La création d’une commande pourrait suivre :

1. client génère une clé d’idempotence;
2. il envoie POST /commandes avec version de contrat;
3. l’API valide types, produits et autorisation;
4. une transaction écrit commande et clé;
5. la réponse retourne 201, emplacement et version;
6. si la réponse se perd, le client renvoie la même clé;
7. l’API retourne la commande existante.

Les codes HTTP distinguent entrée invalide, absence d’identité, refus, conflit et panne. Un 500 pour toute erreur empêche le client de décider entre corriger, abandonner et reprendre. Le corps d’erreur contient code stable et corrélation, pas une trace SQL.

Le contrôle de concurrence utilise un ETag ou une version. PUT avec version 7 échoue si la ressource est déjà 8. Sans cela, la dernière écriture efface silencieusement le changement précédent.

Faire évoluer sans surprendre

Ajouter un champ optionnel est compatible. Renommer ou changer son sens ne l’est pas. Je documenterais schéma, exemples, limites, pagination et dates de retrait. Les tests de contrat vérifient les consommateurs connus. Une période où ancien et nouveau coexistent permet la migration.

Les API ont quotas, timeout et budget de latence. Un client utilise cache et reprises avec attente. Le serveur protège ses dépendances avec disjoncteur et file pour le travail asynchrone. Les métriques suivent taux d’erreur par code, 95e percentile, consommation et âge des files.

TLS protège le transport; OAuth ou certificats donnent une identité; les scopes limitent les actions. L’autorisation vérifie aussi l’objet. Les secrets tournent et les données sensibles ne passent pas dans URL ou logs.

Documenter la pagination comme une garantie

Une liste non bornée fonctionne avec cent produits et tombe avec un million. L’API fixe une taille maximale et retourne un curseur opaque lié à l’ordre stable. Le client transmet ce curseur; il ne calcule pas un numéro de page sur une table qui change. Un filtre et un tri font partie du curseur afin d’éviter le mélange. Si des produits sont ajoutés pendant la lecture, la documentation indique si le client voit un instantané ou un flux évolutif. Le serveur limite aussi la complexité des filtres et indexe les chemins permis. Je testerais page vide, dernier élément supprimé et reprise après expiration, car les exports et synchronisations dépendent souvent davantage de cette mécanique que de la première réponse.

Je publierais une API avec un exemple exécutable et un bac à sable, puis je couperais sa dépendance pendant un test. Une promesse utile explique non seulement le succès, mais comment reconnaître le conflit, la limite et le résultat incertain. C’est là que deux systèmes commencent vraiment à parler le même langage.