Sujet : api-design
-
Bien utiliser les codes de statut HTTP : le premier aiguillage du client
Les clients, caches et agents décident uniquement à partir du code de statut s'il faut réessayer, recharger ou abandonner : 201/204 pour un succès avec ou sans corps, 401 contre 403 pour une authentification manquante contre une autorisation manquante, 409/412/428 pour les conflits et les conditions préalables, 429 et 503 avec Retry-After pour signaler « plus tard ». Un 200 accompagné d'un objet d'erreur trompe tout le monde.
-
Des types d'erreur exploitables par machine réduisent les nouvelles tentatives nuisibles des agents
Hypothèse : lorsqu'une API renvoie des types de problème stables assortis d'indications sur les nouvelles tentatives, les clients automatisés réémettent moins de requêtes qui ne devraient pas être retentées et produisent moins d'écritures en double qu'avec des erreurs uniquement en texte libre ; une comparaison est proposée.
-
Ralentir côté client : Retry-After, en-têtes RateLimit et budgets par hôte
Face aux réponses 429 et 503 et aux en-têtes indicatifs de limitation de débit, un agent doit respecter exactement Retry-After ou, à défaut, appliquer un backoff exponentiel avec aléa, lire les champs RateLimit et RateLimit-Policy fournis par le serveur pour ralentir avant la limite, maintenir un budget par hôte et par clé et ne jamais retenter une écriture non idempotente sans clé d’idempotence.
-
Concevoir des limites de débit qui protègent le service et informent le client
Limiter selon l'identité que l'on peut vérifier (compte, préfixe réseau), utiliser des compteurs atomiques dans des fenêtres fixes ou glissantes, répondre 429 avec Retry-After, garder des budgets séparés pour les lectures, les écritures et les inscriptions, et publier les limites effectives.
-
Pagination de l'API Stripe et clés d'idempotence : starting_after, has_more et la fenêtre de 24 heures
Les endpoints de liste v1 de Stripe paginent avec les paramètres de curseur mutuellement exclusifs starting_after/ending_before (limit de 1 à 100, 10 par défaut) et un indicateur has_more, des assistants de pagination automatique des bibliothèques clientes permettant de parcourir toutes les pages. Les requêtes POST peuvent porter un en-tête Idempotency-Key dont Stripe rejoue le résultat enregistré pendant environ 24 heures, après quoi les clés peuvent être supprimées. Les requêtes limitées reçoivent un 429 avec un en-tête Stripe-Rate-Limited-Reason.
-
Nommage et casse cohérents des champs JSON
Choisir une seule convention de casse pour les noms de propriétés et l'appliquer partout : le guide de style JSON de Google et ProtoJSON utilisent le lowerCamelCase, de nombreuses API utilisent le snake_case. Au-delà de la casse, garder des noms porteurs de sens, des énumérations sous forme de chaînes, des horodatages en chaînes RFC 3339 et des entiers 64 bits en chaînes.
-
La spécification Standard Webhooks face à l'en-tête HMAC de Shopify et au jeton secret partagé de GitLab
La spécification Standard Webhooks définit les en-têtes webhook-id, webhook-timestamp et webhook-signature, un secret en base64 préfixé par whsec_ dont les octets décodés servent de clé HMAC, et une signature v1,<base64> calculée sur « {id}.{timestamp}.{payload} » ; les jetons de signature de GitLab (GitLab 19.0, disponibles en GA dans la 19.1) l'implémentent à l'identique. Shopify envoie à la place un HMAC en base64 du corps brut dans X-Shopify-Hmac-SHA256, et l'ancien X-Gitlab-Token de GitLab est un simple secret partagé, pas un HMAC.
-
Valider du JSON avec JSON Schema
JSON Schema décrit la forme autorisée d'un document (types, clés requises, énumérations, formats, bornes) et permet à n'importe quel langage de valider des entrées avant de les traiter ; garder additionalProperties explicite.
-
Concevoir des opérations idempotentes et des nouvelles tentatives sûres
Une opération est idempotente lorsque son exécution répétée produit le même effet qu'une exécution unique ; la RFC 9110 fixe cela pour les méthodes HTTP, et un en-tête de clé d'idempotence transpose cette propriété à POST. Stocker la clé avec une empreinte et le résultat, signaler les conflits par 409 et 422, supprimer les clés après un délai documenté.
-
Appeler l'API TypeSafe depuis un agent : forme de la requête, erreurs, tentatives et épinglage de version
Le contrat documenté dont un agent a besoin pour appeler Jev sans couche de discussion (chat) : POST /v1/systemone avec une clé Bearer, un état (state), un nom de modèle et une carte de questions typées ; des réponses indexées comme les questions, plus un bloc d'usage ; les codes 401, 422, 429 et 529 avec un backoff exponentiel ; des alias qui évoluent et des identifiants versionnés qui restent fixes ; les valeurs par défaut du SDK pour les tentatives, et la compétence (skill) dédiée aux agents de codage.
-
Modes simulation (dry-run) pour les actions d'un agent : montrer le plan avant le changement
Doter chaque outil qui modifie un état d'un mode qui calcule et retourne le plan concret (quels objets, quels champs, combien) sans l'appliquer, valider le plan côté serveur là où le système le permet, exiger que le plan soit produit et revu avant l'appel réel, et comparer le résultat réel avec lui a posteriori.
-
L'en-tête Link et les types de relation de lien
La RFC 8288 permet à toute réponse HTTP de porter des liens typés dans un en-tête Link : <cible>; rel="relation" plus des paramètres facultatifs anchor, hreflang, type, title et media. Les noms de relation proviennent du registre IANA (next, prev, canonical, alternate, describedby, preload) ou sont des URI absolues pour des extensions privées. C'est ainsi que les réponses non HTML pointent vers leurs voisines, et comment le code 103 Early Hints indique à un navigateur quoi récupérer en avance.
-
HEAD et OPTIONS : à quoi ils répondent et à quoi les clients les utilisent
HEAD est un GET sans corps : même statut et mêmes en-têtes (Content-Length et Vary peuvent être omis), mise en cache possible, utilisé pour la vérification de liens, les sondes de taille et les contrôles de fraîcheur. OPTIONS demande quelles options de communication une ressource ou le serveur entier (OPTIONS *) prend en charge, reçoit typiquement une réponse avec Allow, n'est pas mis en cache, et porte les préflights CORS avec Access-Control-Request-Method.
-
Vérifier les signatures des requêtes Slack : X-Slack-Signature, fenêtre anti-rejeu de 5 minutes et règle des 3 secondes
Slack signe ses requêtes sous la forme v0=<HMAC-SHA256 en hexadécimal> de la chaîne "v0:{timestamp}:{corps brut}", dans l'en-tête X-Slack-Signature, accompagné de X-Slack-Request-Timestamp ; l'exemple de Slack rejette la requête si cet horodatage s'écarte de plus de cinq minutes de l'heure locale. Les commandes slash et les payloads interactifs doivent en outre être acquittés en moins de trois secondes, avant tout traitement long.
-
Concevoir un SDK par-dessus une API HTTP
Un SDK doit faire de l'appel correct l'appel facile : modèles typés, un objet client unique portant la configuration, des erreurs uniformes, des tentatives avec clés d'idempotence, des itérateurs de pagination et des aides pour les opérations longues, générés à partir de la description de l'API quand c'est possible et écrits à la main seulement là où la génération ne peut pas exprimer l'intention.
-
Concevoir des webhooks sortants auxquels les destinataires peuvent faire confiance
Signer chaque livraison avec un HMAC sur le corps et un horodatage, livrer au moins une fois avec des tentatives et des identifiants d'événement idempotents, garder les charges utiles petites avec un lien pour récupérer les détails, et laisser les destinataires vérifier sans secrets dans les URL.
-
Points d'accès en masse et signalement des échecs partiels
Un point d'accès en masse réussit ou échoue en bloc, ou bien signale le résultat de chaque élément ; un simple 200 ne peut pas exprimer un succès partiel, d'où la nécessité de choisir un comportement par point d'accès, d'indexer les échecs par position, de plafonner la taille du lot et d'appliquer l'autorisation et la limitation de débit à chaque élément.
-
Choisir délibérément les codes de statut HTTP
Le code de statut est le premier élément sur lequel un client fonde sa décision : 200/201/204 pour le succès, 304 pour l'absence de changement, 400/422 pour une entrée invalide, 401/403 pour distinguer les identifiants de l'autorisation, 404 pour une ressource absente, 409/412/428 pour les conflits et les préconditions, 429/503 pour réessayer plus tard.
-
Protocoles agent-à-agent en esquisse : cartes d'agent A2A, tâches et la place du MCP
Ce que le protocole A2A (version 1.0.0, Linux Foundation) normalise entre agents indépendants : une Agent Card publiée sur /.well-known/agent-card.json, avec les capacités, les compétences, le point de terminaison et les schémas de sécurité ; des tâches dont le cycle de vie passe par submitted, working, input-required, auth-required, completed, failed, canceled et rejected ; des messages et des artefacts composés de parts ; des liaisons JSON-RPC, gRPC et REST ; et le propre compte rendu de la spécification sur la façon dont elle complète le MCP.
-
La négociation Accept-Language et ses limites
Accept-Language porte une liste pondérée de plages de langues (da, en-gb;q=0.8, en;q=0.7) ; le serveur la confronte aux langues dont il dispose au moyen du filtrage ou de la recherche (lookup) de la RFC 4647, répond avec Content-Language et Vary: Accept-Language, et doit se rabattre intelligemment lorsque l'en-tête est absent (Googlebot n'en envoie aucun) ou erroné (la locale d'un appareil n'est pas le choix du lecteur). À utiliser pour une première estimation, pas comme unique sélecteur.
Lisible par machine : JSON