Travail final

Ce que vous saurez faire

Modifiez une vraie API comme le fait une équipe. Convenez d’abord du contrat, puis créez le point de terminaison et documentez-le. Testez-le de l’intérieur et de l’extérieur, déployez-le et prouvez que le déploiement fonctionne. Vous ajoutez un point de terminaison à votre projet ticket-api et conservez des preuves de chaque partie.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 300 minutes

Ce que vous devez savoir

• Vous avez terminé les modules 1 à 7. Chaque partie ci-dessous indique les leçons qu’elle utilise.
• Vous n’avez pas besoin des études de cas du module 8 pour ce travail. (Le certificat exige au moins l’une d’elles.) Pour voir d’abord une modification semblable dans un vrai projet, ouvrez Servir un modèle de prix des maisons. Cette étude ajoute un point de terminaison par lots et indique l’élément et le champ dans chaque erreur. Elle adapte aussi la limite du corps au plus grand lot valide.

Ce qu’il vous faut sur votre ordinateur

• Votre projet ticket-api, dans son état à la fin de Vérifier et nettoyer : exercice guidé : vérifier et nettoyer. python -m pytest réussit.
• Si votre projet manque ou ne fonctionne plus, copiez l’instantané end-of-m07, le projet à la fin du module 7. Utiliser un instantané explique les étapes. Il ne contient aucune application déployée ni aucune clé : la partie 6 en crée de nouvelles.
• La collection Postman s’exécute depuis le terminal, comme dans Tests et exécutions reproductibles : exécuter depuis le terminal : Postman CLI.
• Pour la partie 6, un compte FastAPI Cloud, comme dans Publier en toute sécurité : étape 1 : se connecter et créer l’application, ou la simulation de déploiement local de Premiers pas avec l’hébergement : exemple détaillé : le mode production sur votre ordinateur.
• Vous pouvez faire le travail en plusieurs séances. Exécutez les tests après chaque modification.

La situation

Le système du service de soutien envoie maintenant les billets de soutien en groupes. Toutes les quelques minutes, il rassemble jusqu’à 20 nouveaux billets. Il appelle ensuite l’API une seule fois pour tous les billets, plutôt que 20 fois. La personne responsable du service de soutien demande :

1. Un point de terminaison par lots. POST /v1/classify/batch, avec un corps contenant de 1 à 20 billets, chacun valide selon les règles de /v1/classify. La réponse contient une classification par billet, dans le même ordre.
2. Les mêmes protections. La clé d’API, la limite de temps et la limite de taille du corps s’appliquent, comme pour un seul billet.
3. Des erreurs claires. Une liste vide, plus de 20 billets ou un billet invalide donne 422. L’erreur indique le champ : pour le sujet du quatrième billet, tickets.3.subject (la liste commence à 0).
4. Aucun changement pour les clients existants. Tout ce qui fonctionne aujourd’hui continue de fonctionner, exactement comme avant.

Règles pour chaque partie

• Gardez la structure : les modèles dans models.py, la route dans routes.py et le classificateur inchangé.
• Après chaque modification, exécutez python -m pytest. Quand le test du contrat échoue, lisez les différences avant l’exportation, comme dans Garder la documentation exacte.
• Aucun secret dans les fichiers : ni dans le code, ni dans postman/, ni dans vos preuves.
• Créez un fichier evidence.md à l’extérieur du dossier du projet, par exemple ~/projects/c16-evidence.md. Après chaque partie, copiez-y les sorties demandées.

Partie 1 : le contrat d’abord

Utilise Conception des ressources et des points de terminaison et Validation et réponses d’erreur.

1. Rédigez le tableau du contrat pour POST /v1/classify/batch : le corps de la requête, celui de la réponse et une ligne par échec. Les échecs sont : aucune clé, liste vide, 21 billets, un billet invalide, champ inconnu, classificateur indisponible et corps trop volumineux.
2. Choisissez la version. Un nouveau point de terminaison est-il un changement incompatible? Quelle est la nouvelle version dans FastAPI(...)?
3. Faites le calcul : 20 billets, chacun avec un corps de 1 000 caractères. Cette requête respecte-t-elle la limite de 16 Ko du corps? Décidez quoi faire et inscrivez votre décision dans le tableau : modifier une limite ou la documenter.

Preuves pour la partie 1 : le tableau du contrat, le choix de version et la décision sur la taille. Justifiez chaque décision en une phrase.

Partie 2 : créer le point de terminaison

Utilise Modèles de requête et de réponse, Séparer les responsabilités et Protection de base.

1. Ajoutez un modèle de requête (une liste de TicketIn, de 1 à 20 éléments, sans champs inconnus). Ajoutez aussi un modèle de réponse (une liste de Classification).
2. Ajoutez la route. Elle utilise la même dépendance de classificateur, la même vérification de clé d’API et la même limite de temps pour tout le lot.
3. Vérifiez manuellement : envoyez l’exemple de votre tableau du contrat avec curl ou Postman.

Preuves pour la partie 2 : la requête et la réponse d’un lot de deux billets.

Pour un lot contenant {"subject": "Charged twice for March"} et {"subject": "Parcel lost"}, les résultats sont billing (facturation) et shipping (expédition), dans cet ordre. Les deux ont la priorité 1 et un degré de confiance de 0.7.

Partie 3 : documenter le point de terminaison

Utilise Une documentation utilisable et Garder la documentation exacte.

1. Donnez à la route un résumé et une description qui précise les limites et l’ordre des résultats. Ajoutez chaque réponse d’erreur documentée avec ErrorResponse.
2. Donnez aux deux modèles un exemple qui fonctionne.
3. Exécutez les tests. Lisez les différences du contrat : le nouveau point de terminaison, les nouveaux schémas et la nouvelle version. Exportez ensuite le contrat.
4. Ajoutez un test qui envoie l’exemple de lot de la documentation. Vérifiez qu’il donne 200 avec un résultat par billet.

Preuves pour la partie 3 : les différences du test du contrat (les premières lignes suffisent) et une capture du nouveau point de terminaison ouvert dans /docs.

Partie 4 : tester le point de terminaison

Utilise Tests automatisés des points de terminaison et Configuration et journalisation.

Écrivez des tests pytest pour vérifier au moins :

1. L’ordre des résultats.
2. Les limites de la liste : 0, 1, 20 et 21 billets.
3. Un billet invalide dans la liste et le champ exact dans l’erreur.
4. Une clé manquante, lorsqu’une clé est définie.
5. Le classificateur indisponible (classifier_mode="unavailable").
6. Votre décision sur la taille de la partie 1.

Rendez ensuite la route incorrecte volontairement, par exemple en inversant les résultats, et vérifiez qu’un test échoue.

Preuves pour la partie 4 : les fonctions de test et la sortie de python -m pytest où tous les tests réussissent.

Partie 5 : Postman

Utilise Premières requêtes dans Postman et Tests et exécutions reproductibles.

1. Ajoutez au moins deux requêtes à la collection. La première est un lot valide (tests : statut, un résultat par billet, ordre). La deuxième est un lot vide (tests : 422, champ tickets).
2. Exportez la collection dans postman/ et vérifiez qu’aucun fichier de ce dossier ne contient de clé.
3. Exécutez toute la collection depuis le terminal contre l’API locale, avec la clé fournie par --env-var.

Preuves pour la partie 5 : le tableau récapitulatif de l’exécution dans le terminal et son code de sortie.

Partie 6 : déployer et vérifier

Utilise Premiers pas avec l’hébergement, Publier en toute sécurité et Vérifier et nettoyer.

Avec FastAPI Cloud

1. Créez l’application, définissez une nouvelle clé d’API comme secret et définissez SHOW_DOCS avant le déploiement.
2. Déployez. Vérifiez /health, /ready et une requête par lots sans clé (401).
3. Exécutez la collection avec l’environnement Deployed (déployé).
4. Définissez CLASSIFIER_MODE=unavailable et montrez qu’une requête par lots donne 503 avec un identifiant de requête. Trouvez cette requête dans les journaux (logs). Retirez ensuite le paramètre.
5. Supprimez l’application, dissociez le dossier et retirez la clé de Postman.

Simulation locale

1. Dans un nouvel environnement virtuel contenant seulement les dépendances de pyproject.toml, démarrez l’API avec fastapi run, une clé et SHOW_DOCS=false.
2. Vérifiez /health, /ready, /docs (404) et une requête par lots sans clé (401).
3. Exécutez la collection contre cette API.
4. Redémarrez-la avec CLASSIFIER_MODE=unavailable et montrez qu’une requête par lots donne 503 avec un identifiant de requête. Trouvez cette requête dans le journal.
5. Écrivez deux phrases sur ce qu’un vrai déploiement ajouterait et que cette simulation ne montre pas.

Preuves pour la partie 6 : les sorties de chaque étape (sans la clé). Pour FastAPI Cloud, ajoutez une ligne indiquant que l’application est supprimée.

Vérifiez votre travail

Personne ne révise encore les travaux de ce cours. Examinez vos preuves avec ce tableau ou demandez à un collègue de le faire. Marquez chaque élément comme démontré, partiellement démontré ou pas encore démontré, avec une justification. Le cours est terminé quand chaque élément est démontré. Vous pouvez améliorer un élément et le réexaminer aussi souvent que nécessaire.

Preuve requise	Démontré quand
Contrat documenté du point de terminaison	Le tableau du contrat couvre chaque ligne d’échec. Le document OpenAPI contient le point de terminaison avec une description, des exemples fonctionnels et chaque réponse d’erreur. Le fichier du contrat révisé correspond, et un test prouve que l’exemple documenté fonctionne. Le changement de version est expliqué.
Validation des entrées et des erreurs	Chaque ligne du tableau du contrat donne le code de statut et la structure d’erreur prévus. Cela comprend les limites 0, 1, 20 et 21, et le champ exact d’un billet invalide. Les erreurs ne contiennent jamais de détails internes.
Une collection Postman qui s’exécute depuis la ligne de commande	La collection est dans le projet, avec des tests pour le point de terminaison par lots. Elle s’exécute depuis le terminal. Tous les tests réussissent contre l’API locale et l’API déployée (ou simulée). Elle échoue avec le code de sortie 1 quand l’API est indisponible.
Vérifications reproductibles en local et après déploiement	pytest réussit. L’API déployée ou simulée réussit les tests de la collection. Elle montre une requête réussie, une requête invalide et une défaillance contrôlée d’une dépendance (503 avec un identifiant de requête).
Secrets hors du code source	Aucune clé dans le code, dans postman/, dans le README ou dans les preuves. La clé déployée était nouvelle, stockée comme secret et supprimée après le nettoyage.

Le fonctionnement du cas normal ne suffit pas. Une requête sans clé pourrait recevoir 200 alors qu’une clé est définie, ou une erreur pourrait afficher une trace d’exception. L’élément est alors pas encore démontré, même si tout le reste fonctionne.

Assistants d'IA

Vous pouvez utiliser un assistant d’IA pour vous exercer et surmonter un blocage. Vous devez pouvoir expliquer le travail que vous remettez. Pour chaque modification, dites ce qu’elle fait, pourquoi elle est correcte et quel test le prouve. Un assistant qui écrit un test sans d’abord montrer un cas qui échoue ne vous a rien démontré.

Erreur courante

20 billets sont permis, mais 20 billets donnent 413

Symptôme : un lot de 20 billets avec de longs corps donne 413 body_too_large (corps trop volumineux). Pourtant, le contrat permet jusqu’à 20 billets.

Cause : deux limites se rencontrent. Le corps de chaque billet peut contenir 5 000 caractères, et 20 de ces billets représentent environ 100 Ko. Mais la requête entière ne peut dépasser 16 Ko. Les deux limites sont correctes pour un seul billet. Ensemble, elles se contredisent pour un lot.

Solution : prenez une décision et faites en sorte que le contrat dise la vérité. Une option consiste à augmenter la limite du corps pour le point de terminaison par lots et à accepter l’utilisation accrue de mémoire. L’autre consiste à garder 16 Ko. Documentez alors dans la description du point de terminaison que le lot entier doit tenir dans 16 Ko, avec un test. Les deux options sont valides. Une contradiction non documentée ne l’est pas.

Récapitulatif

Dans ce cours, vous êtes passé d’une requête HTTP à un service déployé auquel d’autres programmes peuvent se fier :

• HTTP : URL, DNS, ports et TLS, méthodes, en-têtes, corps et codes de statut, et comment les examiner.
• Le service : routes FastAPI, modèles typés, classificateur séparé et structure d’erreur unique avec des codes stables.
• Le contrat : routes avec versions, CORS pour les navigateurs et documentation OpenAPI dans Swagger UI, gardée exacte par les tests.
• Postman : collections, environnements Postman, secrets conservés seulement en local, tests et exécutions depuis la ligne de commande.
• Fiabilité : pytest pour chaque cas, identifiants de requête dans les journaux, clé d’API, limite du corps et limite de temps.
• Déploiement : mode production, secrets sur la plateforme, vérifications de fonctionnement et de disponibilité, vérifications rapides, journaux et nettoyage.

Les cours suivants s’appuient sur cette API. Ils déploient un modèle entraîné derrière elle et la placent dans un conteneur. Ils exécutent aussi automatiquement la collection Postman à chaque mise en production.