Temps de lecture estimé : 10 min · Publié le
Choisir les tâches avant les adresses
Recensez les usages : chercher un produit, lire une disponibilité, mettre à jour une fiche ou suivre un traitement. Définissez les personnes et systèmes autorisés pour chaque opération. Une API publique en lecture et une API d’administration n’ont pas les mêmes règles d’accès.
Préparez un exemple de demande et de réponse pour chaque tâche essentielle, avec des valeurs fictives et des champs expliqués. Distinguez identifiant stable, libellé, unité et date. Indiquez les données absentes et évitez de remplacer une information inconnue par une valeur plausible.
Précisez la représentation des grands identifiants avant de choisir un exemple JSON. Avec les nombres binary64 utilisés par Number en JavaScript, les entiers de −9007199254740991 à 9007199254740991 peuvent être échangés exactement dans la plage d’interopérabilité décrite par la RFC 8259. Le nombre 9007199254740992 reste représentable, mais sort de la plage des entiers sûrs : le jeton voisin 9007199254740993 est arrondi à 9007199254740992 par le décodage JSON JavaScript standard montré ici.
Dans cet exercice, le même identifiant écrit comme chaîne JSON conserve ses chiffres. Ce choix doit être prévu dans le contrat du producteur, du schéma et du consommateur ; convertir en texte un Number déjà arrondi ne retrouve pas la valeur d’origine. D’autres bibliothèques peuvent conserver davantage de précision : testez les clients effectivement pris en charge. Un JSON syntaxiquement valide ne garantit donc pas la fidélité des valeurs, et le type d’un identifiant ne doit pas changer silencieusement entre deux réponses.
Faites défiler le tableau horizontalement pour lire toutes les colonnes. Au clavier, placez le focus sur le tableau puis utilisez les flèches.
| Jeton JSON de démonstration | Valeur JavaScript affichée | Interprétation |
|---|---|---|
| 9007199254740991 | 9007199254740991 | Entier sûr dans cet exemple |
| 9007199254740992 | 9007199254740992 | Exactement représenté, mais hors plage des entiers sûrs |
| 9007199254740993 | 9007199254740992 | Valeur arrondie : le dernier chiffre initial est perdu |
| "9007199254740993" | "9007199254740993" | Chaîne exacte ; type textuel prévu par le contrat |
Décrire un contrat explicite
OpenAPI fournit un format de description des API HTTP indépendant du langage. Il permet de décrire les opérations, paramètres, réponses et modèles. Choisissez une version prise en charge par vos outils et conservez le document avec le projet ; la version la plus récente n’est pas automatiquement la bonne pour chaque chaîne.
Complétez le contrat avec limites d’usage, pagination, filtre, ordre, états d’erreur et exemple de réponse vide. Ne traitez pas CORS comme une preuve d’autorisation : vérifiez les contrôles d’accès propres à chaque opération et chaque objet avec l’équipe technique.
Pour une API fictive de traitement de demandes, décrivez séparément les quatre réponses ci-dessous. Dans ce contrat, 201 renvoie une ressource créée avec son en-tête Location ; 202 fournit une référence de suivi parce que le travail n’est pas terminé. Ne transformez pas toutes les réponses de la famille 2xx en message « opération achevée ». Le client doit lire le statut, les en-têtes et le modèle prévu pour cette opération.
Le cas 204 ne contient pas de corps à décoder en JSON. Dans cet exemple, une instruction de format correct mais contraire à une règle métier reçoit 422 avec un problème structuré en application/problem+json. Si le membre status est fourni, son générateur doit le faire correspondre au statut HTTP réel ; un texte traduit dans detail ne doit pas devenir la clé de décision du logiciel. Documentez les identifiants stables de problème et l’action de correction attendue.
Faites défiler le tableau horizontalement pour lire toutes les colonnes. Au clavier, placez le focus sur le tableau puis utilisez les flèches.
| Réponse prévue | Fait établi | Contrôle du consommateur |
|---|---|---|
| 201 Created | Ressource créée | Vérifier Location prévu par ce contrat et l’identifiant créé |
| 202 Accepted | Traitement accepté, non terminé | Conserver la référence de suivi ; attendre le résultat final |
| 204 No Content | Action réussie, sans corps de réponse | Ne pas lancer de décodage JSON sur un corps vide |
| 422 Unprocessable Content | Instruction comprise mais non traitable selon la règle | Lire le problème structuré et proposer une correction adaptée |
- RFC 9110 : HTTP Semantics
RFC 9110, consultée le 22 octobre 2026 : sémantique des statuts. Les réponses et champs exigés ici définissent un contrat fictif.
- RFC 9457 : Problem Details
RFC 9457, consultée le 22 octobre 2026 : format des problèmes et rôle du membre status.
Empêcher une modification d’écraser celle d’un autre éditeur
- Deux lectures de r7
- Première écriture : r8
- Ancienne écriture : 412
- Comparer avant de reprendre
Scénario fictif : deux éditeurs ouvrent la fiche DEMO-17 avec l’ETag fort "r7". Le premier enregistre une correction ; la représentation courante devient "r8". Le second travaille encore sur sa copie de "r7". Une écriture conditionnelle permet de détecter ce décalage avant de remplacer la version publiée.
Dans une API qui prend en charge ce contrat, le client transmet If-Match avec le validateur fort reçu. Le serveur compare la version avant l’écriture : notre scénario prévoit 412 si elle a changé. W/"r7" est un validateur faible et ne satisfait pas cette comparaison forte. If-Match: * vérifie l’existence d’une représentation courante, pas l’absence de modification depuis sa lecture.
Gardez le brouillon du second éditeur, relisez la version courante et présentez les différences avant de soumettre une nouvelle décision. Remplacer automatiquement le validateur par "r8" puis renvoyer l’ancien brouillon contournerait la protection. La vérification et l’écriture doivent être indivisibles côté stockage ; deux requêtes concurrentes portant le même validateur ne doivent pas toutes deux écraser la même version.
Ce contrôle de concurrence ne remplace ni l’authentification, ni les droits sur la fiche, ni la validation des champs. Il ne garantit pas non plus l’exécution unique d’un appel externe. Testez séparément ces propriétés et documentez le comportement lorsque la précondition manque ; 428 peut servir à exiger une requête conditionnelle.
Faites défiler le tableau horizontalement pour lire toutes les colonnes. Au clavier, placez le focus sur le tableau puis utilisez les flèches.
| Étape | Version et requête | Résultat prévu par ce contrat |
|---|---|---|
| Lecture des deux éditeurs | ETag: "r7" | Chacun conserve le validateur avec son brouillon. |
| Premier enregistrement | If-Match: "r7" → version "r8" | La correction du premier éditeur est conservée. |
| Second enregistrement resté ancien | If-Match: "r7" ; version courante "r8" | 412 ; ne pas remplacer la correction déjà enregistrée. |
| Rapprochement explicite | Relire "r8", comparer, puis décider | Conserver le brouillon et vérifier les droits avant toute nouvelle écriture. |
- IETF · RFC 9110 § 13.1.1
IETF : Écritures conditionnelles et préconditions
- IETF · RFC 6585 § 3
428 · Precondition Required
Tester les limites et les permissions
Essayez un objet présent, un objet absent, un paramètre invalide et une liste plus longue qu’une page. Vérifiez que le passage à la page suivante ne perd ni ne répète les objets dans le contexte de mise à jour choisi. Décrivez les limites que votre API ne peut pas garantir.
Utilisez des comptes de test aux droits différents. Tentez une consultation ou modification hors du périmètre autorisé, sans données réelles. Conservez le statut attendu et un message utile, sans révéler au destinataire une trace interne ou un secret de configuration.
Faites défiler le tableau horizontalement pour lire toutes les colonnes. Au clavier, placez le focus sur le tableau puis utilisez les flèches.
| Situation ou réglage | Ce que cela signifie | Vérification utile |
|---|---|---|
| Liste vide | La requête réussit, mais aucun élément ne correspond. | Vérifier le modèle documenté, le nombre d’éléments et la suite de pagination. |
| Champ absent, null ou chaîne vide | Ces représentations ne portent pas nécessairement le même sens. | Documenter chaque cas admis et tester les clients qui consomment ce champ. |
| Objet hors du périmètre autorisé | Une adresse connue ne donne pas le droit de consulter l’objet. | Tester les droits côté serveur avec deux comptes et des données d’essai. |
Prévoir évolutions et support
Distinguez un champ ajouté d’un champ supprimé ou dont le sens change. Recensez les consommateurs avant une modification incompatible. Expliquez la période de transition et le moyen de vérifier qu’une intégration utilise encore l’ancien contrat.
Livrez un exemple qui s’exécute dans un environnement d’essai, une matrice de tests et un contact technique. Après publication, rapprochez les erreurs observées des exemples documentés. Une documentation qui décrit seulement le cas idéal laisse les intégrateurs seuls face aux refus et interruptions.
Documentation primaire : OpenAPI Initiative : Specification.
Documents de référence
- OpenAPI Initiative : Specification · Source consultée
- OWASP : Authorization Cheat Sheet · Source consultée
- MDN : CORS · Source consultée
- IETF : RFC 8259: JSON numbers · Source consultée
- TC39 : Number.isSafeInteger · Source consultée
Contenu mis à jour le
Repères documentaires pour ce sujet
| Référence | Valeur ou syntaxe | Portée du repère |
|---|---|---|
| RFC 8259 · JSON | application/json · UTF-8 | JSON standard n’autorise ni commentaires ni virgule finale ; les chaînes utilisent des guillemets doubles. |
| RFC 3339 · Date-time | 2026-10-22T09:00:00+02:00 | Le décalage explicite relie l’heure locale à UTC ; cet exemple n’est pas un rendez-vous. |
| HTTP · If-Match | If-Match: "r7" → 412 | If-Match compare un validateur fort avant une écriture. Dans le contrat présenté, une version dépassée reçoit 412 ; le brouillon est conservé pour comparer les changements. |
| HTTP · 428 | 428 · Precondition Required | 428 permet au serveur d’exiger une requête conditionnelle. Son usage doit être décrit dans le contrat ; il ne fournit pas lui-même de verrouillage. |
Les dates indiquent la consultation des références. Ces repères ne constituent ni un audit du site ni une déclaration globale de conformité.
