Faire évoluer les contrats API sans perdre les clients

HTTP 422 · Content-Type: application/problem+json

{
    "type": "https://api.example.net/problems/invalid-window",
    "title": "Invalid time window",
    "status": 422,
    "detail": "The end must follow the start.",
    "instance": "/problems/events/test-17",
    "errors": [
        {
            "field": "end",
            "code": "before-start"
        }
    ]
}

Lecture : Le statut du corps et celui de la réponse concordent. Le tableau errors est une extension propre à cet exemple, pas un membre standard universel.

Test à ajouter : Tester le code stable before-start et l’association au champ ; ne pas analyser le texte detail pour automatiser la correction.

HTTP 404 · Content-Type: application/problem+json

{
    "title": "Ressource introuvable",
    "instance": "/support/test-18"
}

Lecture : Les cinq membres ne forment pas une liste de champs tous obligatoires. Sans type exploitable, about:blank s’applique ; le statut HTTP reçu reste 404.

Test à ajouter : Vérifier que le client accepte cette réponse minimale et un titre localisé, sans inventer un statut stocké dans le corps.

HTTP 200 · Content-Type: application/problem+json

{
    "type": "https://api.example.net/problems/access-denied",
    "title": "Access denied",
    "status": 403
}

Lecture : Il existe un écart entre deux couches. Le statut conseillé dans le JSON ne remplace pas celui reçu par les clients HTTP génériques.

Test à ajouter : Examiner la génération et les intermédiaires ; conserver les deux valeurs plutôt que déclarer la requête réussie à partir du seul HTTP 200.

HTTP 422 · Content-Type: application/problem+json

{
    "type": 17,
    "title": false,
    "status": "422",
    "detail": [
        "Invalid"
    ],
    "instance": null,
    "traceRef": "test-19"
}

Lecture : type, title, status, detail et instance sont de types inattendus. La règle de consommation de la RFC est de les ignorer, sans convertir automatiquement la chaîne "422" en nombre.

Test à ajouter : Signaler le défaut du producteur et tester un client tolérant. traceRef reste une extension ; about:blank est le type par défaut après ignorance de type.

HTTP 409 · Content-Type: application/problem+json

{
    "type": "/problems/conflict",
    "title": "Version conflict",
    "status": 409,
    "instance": "?case=test-20",
    "requestRef": "test-20",
    "retryable": false
}

Lecture : Le type commence par un chemin relatif et instance par une référence de requête. L’atelier les affiche sans les résoudre ; la base du document réel serait nécessaire.

Test à ajouter : Définir la base dans le contrat, préférer un type absolu et tester l’ignorance des extensions non reconnues. Le seul mot retryable ne donne pas un droit universel de rejeu.

HTTP 400 · Content-Type: application/problem+json

{
    "type": "https://iana.org/assignments/http-problem-types#date",
    "title": "Date Not Acceptable",
    "status": 400,
    "instance": "/support/test-21"
}

Lecture : Ce type figure dans la copie IANA. Son statut recommandé est 400. Une comparaison sur le seul suffixe #date ou sur title ne suffit pas à identifier le type.

Test à ajouter : Renvoyer le client vers la définition de ce type dans le contexte applicable ; l’enregistrement ne certifie pas l’implémentation.

HTTP 503 · Content-Type: application/json

{
    "type": "https://api.example.net/problems/maintenance",
    "title": "Service maintenance",
    "status": 503,
    "detail": "Try the documented recovery path."
}

Lecture : Le corps ressemble à un Problem Details, mais le nom du type de média reçu est application/json. Une lecture structurelle ne vérifie pas la négociation ou le contrat de réponse.

Test à ajouter : Comparer Content-Type, documentation et client. Ne pas transformer cet exemple en règle de relance : Retry-After et sécurité du rejeu restent des contrôles séparés.

HTTP 400 · Content-Type: application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 700,
    "instance": "/support/test-22"
}

Lecture : Le membre status est bien un nombre JSON, mais 700 est hors de la plage des codes HTTP à trois chiffres de 100 à 599. Ce défaut est distinct du mauvais type JSON.

Test à ajouter : Réparer la génération et conserver le statut HTTP reçu, ici 400. Un test de type de données seul aurait manqué cette anomalie.