Rechercher
Saisissez au moins deux caractères, sans donnée personnelle.

    BibliothèqueArticles et FAQ Votre projetDemander un devis
    LangueFR
    Guides pratiques

    Documenter et tester une API à partir des usages

    Une API utile permet à une autre équipe de comprendre ce qu’elle peut demander et ce qu’elle recevra. Son contrat doit être testable, versionné et cohérent avec le service réellement exploité.

    Voir la méthode

    Schémas imprimés et ordinateur affichant du code
    Illustration générée par IA

    Choisir les tâches avant les adresses

    Décodage JavaScript : 9007199254740993 numérique est arrondi ; la même suite en chaîne reste exacte.
    Illustration · Démonstration avec JSON.parse standard : le type Number arrondit ici le jeton numérique, tandis que le type String conserve les chiffres. La représentation textuelle doit être prévue au contrat avant la conversion.

    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.

    Décodage JSON JavaScript standard : précision et type
    Jeton JSON de démonstrationValeur JavaScript affichéeInterprétation
    90071992547409919007199254740991Entier sûr dans cet exemple
    90071992547409929007199254740992Exactement représenté, mais hors plage des entiers sûrs
    90071992547409939007199254740992Valeur 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.

    Quatre réponses d’une API fictive et leurs conséquences côté client
    Réponse prévueFait établiContrôle du consommateur
    201 CreatedRessource crééeVérifier Location prévu par ce contrat et l’identifiant créé
    202 AcceptedTraitement accepté, non terminéConserver la référence de suivi ; attendre le résultat final
    204 No ContentAction réussie, sans corps de réponseNe pas lancer de décodage JSON sur un corps vide
    422 Unprocessable ContentInstruction comprise mais non traitable selon la règleLire 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

    1. Deux lectures de r7
    2. Première écriture : r8
    3. Ancienne écriture : 412
    4. 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.

    Deux éditeurs, une version courante : scénario fictif à rejouer
    ÉtapeVersion et requêteRésultat prévu par ce contrat
    Lecture des deux éditeursETag: "r7"Chacun conserve le validateur avec son brouillon.
    Premier enregistrementIf-Match: "r7" → version "r8"La correction du premier éditeur est conservée.
    Second enregistrement resté ancienIf-Match: "r7" ; version courante "r8"412 ; ne pas remplacer la correction déjà enregistrée.
    Rapprochement expliciteRelire "r8", comparer, puis déciderConserver le brouillon et vérifier les droits avant toute nouvelle écriture.

    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.

    Différencier les réponses qui se ressemblent
    Situation ou réglageCe que cela signifieVérification utile
    Liste videLa 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 videCes 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

    Contenu mis à jour le

    Repères documentaires pour ce sujet

    Repères documentaires pour ce sujet
    RéférenceValeur ou syntaxePortée du repère
    RFC 8259 · JSON
    application/json · UTF-8JSON 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:00Le décalage explicite relie l’heure locale à UTC ; cet exemple n’est pas un rendez-vous.
    HTTP · If-Match
    If-Match: "r7" → 412If-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 Required428 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é.

    Distinguer statut HTTP, JSON et résultat métier

    Choisissez un échange fictif, puis essayez sa lecture locale. Un succès HTTP, un JSON lisible et une opération terminée sont trois vérifications différentes.

    Les extraits sont incomplets et utilisent des adresses de démonstration. L’essai crée une Response en mémoire : il ne contacte aucun serveur et ne simule ni réseau, ni cache, ni traitement métier.

    200Nouvelle représentation complète
    Ce que cela signifie
    Dans cet extrait, le serveur répond au GET conditionnel avec un corps JSON et le validateur demo-v2.
    Contrôle à effectuer
    Rapprochez If-None-Match, ETag et la révision du corps. L’essai local lit le JSON réellement fourni dans cet exemple.
    Point de vigilance
    Un statut 200 ne garantit ni un JSON valide ni un contenu métier correct. Ici, la réussite de l’analyse ne valide pas le schéma de vos propres données.
    Extrait d’échange fictif
    GET /demo/catalogue
    If-None-Match: "demo-v1"
    
    HTTP/1.1 200 OK
    ETag: "demo-v2"
    Content-Type: application/json
    
    {"revision":"demo-v2"}

    202Accepté, traitement encore en attente
    Ce que cela signifie
    202 indique une acceptation pour traitement ; il ne confirme pas son achèvement. Le corps fictif indique queued.
    Contrôle à effectuer
    Conservez la référence DEMO-42 et suivez l’état selon le contrat de l’API, avec les droits et limites de relance prévus.
    Point de vigilance
    Response.ok vaut true pour ce statut. Ni cette valeur ni un JSON lisible ne prouvent la fin du traitement. Les champs et l’adresse de suivi de l’extrait sont des conventions fictives.
    Extrait d’échange fictif
    POST /demo/jobs
    
    HTTP/1.1 202 Accepted
    Location: /demo/jobs/DEMO-42
    Content-Type: application/json
    
    {"job":"DEMO-42","status":"queued"}

    204Requête satisfaite, sans corps de réponse
    Ce que cela signifie
    204 indique que le serveur a satisfait la requête sans contenu de réponse. Dans cet extrait, aucun JSON n’est transmis.
    Contrôle à effectuer
    Traitez l’absence de corps selon le contrat. Vérifiez ce que le point de réception confirme exactement avant d’annoncer un résultat au visiteur.
    Point de vigilance
    Une analyse JSON du corps vide échoue alors que Response.ok vaut true. Pour un webhook, l’opération confirmée peut être la réception ; les actions métier ultérieures restent à rapprocher.
    Extrait d’échange fictif
    POST /demo/events
    
    HTTP/1.1 204 No Content

    304Copie revalidée, aucun nouveau corps
    Ce que cela signifie
    304 répond à une requête conditionnelle : la représentation conservée peut être réutilisée. La réponse 304 ne fournit pas un nouveau corps.
    Contrôle à effectuer
    Rapprochez le validateur envoyé et la copie demo-v2 disponible. La bonne lecture dépend aussi de cette copie déjà conservée.
    Point de vigilance
    L’essai construit une Response 304 isolée, pas un cache HTTP. Lors d’un vrai fetch, le cache du navigateur peut fournir la réponse conservée : statut réseau et statut exposé au script peuvent différer.
    Extrait d’échange fictif
    GET /demo/catalogue
    If-None-Match: "demo-v2"
    
    HTTP/1.1 304 Not Modified
    ETag: "demo-v2"

    Références techniques : RFC 9110 §15 · MDN · Response.ok · MDN · Response.json() · WHATWG · Fetch · .

    Matrice de recette à adapter au projet

    Ces contrôles proposés utilisent des cas fictifs. Décidez du comportement attendu avec l’équipe, notez le résultat et attribuez les écarts non résolus avant publication.

    Faites défiler le tableau horizontalement pour lire toutes les colonnes. Au clavier, placez le focus sur le tableau puis utilisez les flèches.

    Cas de test, résultats attendus et preuves utiles
    CasRésultat attenduPreuve à conserver
    Ressource présente et absenteChaque résultat correspond au statut et au modèle documentés.Méthode, chemin, identité de test, statut et corps reçus pour une ressource présente puis absente.
    Paramètre hors limitesLe refus est compréhensible et ne révèle pas de trace interne.Message public et résultat conservé dans la matrice.
    Deux niveaux de droitsUne ressource interdite reste inaccessible malgré un identifiant connu.Comparaison des résultats pour les deux comptes fictifs.
    Suite paginée et filtre modifiéLe comportement du jeton et la reprise du parcours sont définis.Ordre, identifiants obtenus et règles de changement de filtre.

    Questions fréquentes

    Quels essais ajoutent de la valeur à une documentation d’API ?

    Choisissez une opération importante et confrontez exemple documenté et réponse réelle : données valides, champ manquant, identifiant inconnu et compte sans droit. Pour une liste, vérifiez pagination et absence de résultat. Conservez statut, structure attendue et effet observé, en retirant les secrets. Un exemple qui retourne du JSON ne prouve ni les permissions ni la stabilité du contrat.

    Comment vérifier que CORS ne masque pas un défaut de droits ?

    Séparez les deux questions : quelles origines le navigateur peut lire, et quelles opérations le serveur autorise à ce compte. Dans un environnement de test, vérifiez les permissions sur les objets et opérations avec plusieurs comptes prévus pour l’essai. Une réponse inaccessible à un script du navigateur peut malgré tout être accessible à un autre client ; les droits doivent être appliqués par le service.