Presentations_API_Professionnelles_FR_v2.pdf

PRESENTATION 1 - API REST : fondamentaux et bonnes pratiques Slide 1/11
Contenu original - usage pédagogique © 2026
PRESENTATION 1 - API REST : fondamentaux et bonnes
pratiques
Deux supports complets, rédigés en français professionnel. Chaque slide contient un texte explicatif
(plus de 40 mots) et des points clés actionnables. Vous pouvez utiliser ce PDF comme support de
cours, script d’oral ou base pour une version PowerPoint.
Astuce : importez ce PDF dans votre outil de présentation ou utilisez-le comme script de cours.

1. Qu’est-ce qu’une API et pourquoi REST ?
Une API (Application Programming Interface) est un contrat qui permet à une application d’utiliser les
capacités d’un autre service, sans connaître sa logique interne. REST est un style d’architecture qui organise
les échanges autour de ressources accessibles via HTTP. L’intérêt principal est la simplicité : mêmes principes
que le Web, formats courants (JSON), et intégration facile avec des clients variés (mobile, web, back-office).
Points clés
Une ressource représente un objet métier (utilisateur, produit, commande).
HTTP fournit des méthodes standard pour agir sur ces ressources.
La cohérence de conception améliore la lisibilité et la maintenance.

2. Ressources, URI et modélisation
Dans une API REST, on modélise d’abord le domaine : quelles entités sont importantes, quelles relations
existent, et quelles actions doivent être exposées. Chaque ressource reçoit une URI stable, pensée pour être
compréhensible. On privilégie des noms au pluriel pour les collections et des identifiants pour les éléments.
Une bonne modélisation réduit les cas spéciaux et limite les endpoints inutiles.
Points clés
Exemples : /users, /users/42, /orders/2026-00031.
Évitez les verbes dans l’URL : préférez la méthode HTTP.
Concevez des relations : /users/42/orders pour naviguer.

3. Méthodes HTTP et sémantique
Les méthodes HTTP ne sont pas de simples conventions : elles portent une sémantique. GET lit sans modifier,
POST crée, PUT remplace, PATCH modifie partiellement et DELETE supprime. Respecter cette sémantique
facilite l’usage de l’API par des équipes différentes et améliore la compatibilité avec les outils (caches, proxies,
observabilité). Une API cohérente réduit les erreurs et accélère l’intégration.
Points clés
GET doit être idempotent et sans effet de bord.
PUT est idempotent : rejouer la requête donne le même résultat.
POST n’est pas idempotent par défaut : attention aux doublons.

4. Codes de statut et gestion des erreurs
Les codes de statut HTTP rendent l’API auto-explicative : 2xx pour le succès, 4xx pour une erreur côté client,
5xx pour une erreur côté serveur. En complément, le corps de réponse doit fournir un message clair, un code
applicatif stable et, si possible, des détails exploitables (champ invalide, règle métier). Des erreurs bien
structurées font gagner du temps au support et aux développeurs.
Points clés
200/201/204 : succès (création souvent 201).
400/401/403/404/409/422 : erreurs fréquentes côté client.
500/502/503 : erreurs serveur et indisponibilités.

5. Formats, JSON et conventions de champs
Le format JSON est très utilisé parce qu’il est lisible, léger et supporté partout. L’essentiel est de définir des
conventions stables : nommage des champs (camelCase ou snake_case), types cohérents, dates au format ISO
8601, et encodage UTF-8. Documentez aussi les champs optionnels, les valeurs nulles, et la compatibilité
ascendante pour éviter les ruptures lors des évolutions.
Points clés
Dates : 2026-02-01T10:30:00Z (ou offset explicite).
Gardez les mêmes noms de champs dans tout le produit.
Évitez de changer le sens d’un champ déjà publié.

6. Pagination, tri et filtrage
Dès que les collections deviennent grandes, la pagination est indispensable pour la performance et
l’expérience utilisateur. Deux approches dominent : pagination par page (page, pageSize) et pagination par
curseur (cursor, limit). Ajoutez ensuite un tri explicite et des filtres clairs. L’objectif est de permettre des
requêtes efficaces, prévisibles et faciles à reproduire lors du débogage.
Points clés
Pagination par curseur : meilleure stabilité quand les données changent.
Exposez des paramètres de tri : sort=createdAt,-price.
Filtrage : status=paid&createdAfter=2026-01-01.

7. Authentification et autorisation
L’authentification répond à la question « qui êtes-vous ? », tandis que l’autorisation répond à « avez-vous le
droit ? ». Pour les APIs modernes, on utilise souvent des jetons (Bearer tokens) via OAuth2/OpenID Connect, ou
des clés API pour des usages simples. Sécurisez systématiquement via HTTPS, limitez les permissions (principe
du moindre privilège) et consignez les accès sensibles.
Points clés
HTTPS obligatoire : ne jamais transmettre un token en clair.
Scopes/roles pour contrôler l’accès aux ressources.
Rotation des secrets et révocation des tokens en cas d’incident.

8. Performance, cache et ETags
Une API rapide et stable se conçoit : réduire la taille des réponses, limiter la profondeur des objets, et éviter les
appels inutiles. Le cache HTTP peut améliorer fortement les performances pour les données peu changeantes.
Les ETags et If-None-Match permettent des réponses 304 Not Modified, économisant bande passante et temps.
Mesurez les temps de réponse et surveillez les erreurs pour piloter l’amélioration continue.
Points clés
Compressez (gzip/brotli) si votre stack le permet.
ETag + 304 : idéal pour listes et détails consultés souvent.
Mettez des limites : rate limiting et timeouts raisonnables.

9. Versioning et évolutivité
Les APIs vivent longtemps : il faut prévoir les changements sans casser les clients existants. Favorisez la
compatibilité ascendante : ajouter un champ est généralement sûr, supprimer ou renommer ne l’est pas. Le
versioning peut se faire via l’URL (/v1/), un en-tête (Accept) ou un paramètre, mais l’important est la stratégie
et la communication. Planifiez une période de dépréciation claire.
Points clés
Évitez les breaking changes : préférez introduire de nouveaux champs.
Annoncez la dépréciation avec une date de fin de support.
Tenez un changelog et des notes de migration.

10. Documentation et OpenAPI
Une bonne documentation est un accélérateur d’adoption. Décrivez les endpoints, paramètres, exemples de
requêtes/réponses, et règles métier. Le standard OpenAPI (souvent via Swagger) permet de générer une
documentation interactive, des SDKs et des tests. Même une API interne bénéficie d’un contrat clair : cela
réduit les retours et améliore la qualité globale.
Points clés
Incluez des exemples réalistes, pas uniquement des cas idéaux.
Documentez les erreurs et codes de statut, pas seulement le succès.
Gardez la doc synchronisée avec le comportement réel.

PRESENTATION 2 - Postman : tester, documenter et automatiser Slide 1/11
PRESENTATION 2 - Postman : tester, documenter et
automatiser
Deux supports complets, rédigés en français professionnel. Chaque slide contient un texte explicatif
(plus de 40 mots) et des points clés actionnables. Vous pouvez utiliser ce PDF comme support de
cours, script d’oral ou base pour une version PowerPoint.
Astuce : importez ce PDF dans votre outil de présentation ou utilisez-le comme script de cours.

1. Pourquoi Postman dans un projet API ?
Postman est un outil complet pour explorer une API, valider des comportements, partager des collections et
automatiser des tests. Il aide autant au prototypage qu’à la recette : on peut simuler des requêtes, contrôler
les en-têtes, gérer l’authentification, et conserver un historique. En équipe, les collections standardisent les
scénarios de test et réduisent les incompréhensions entre backend, frontend et QA.
Points clés
Accélère le debug : inspection rapide des réponses et statuts.
Centralise les scénarios : collections, dossiers, variables.
Partage et collaboration : workspaces et exports.

2. Concepts clés : requêtes, collections, environnements
Dans Postman, une requête est une opération HTTP paramétrée (URL, méthode, headers, body). Une collection
regroupe des requêtes liées à un même domaine fonctionnel (auth, produits, commandes). Les
environnements permettent de changer facilement de cible (dev, staging, prod) via des variables. Cette
organisation rend les tests reproductibles et limite les erreurs lors des changements d’URL ou de token.
Points clés
Variables : {{baseUrl}}, {{token}}, {{userId}}.
Collections : structurez par parcours utilisateur.
Environnements : évitez les copier-coller entre dev et prod.

3. Authentification : Bearer, OAuth2, API Key
Postman simplifie l’ajout d’authentification, mais il faut rester rigoureux. Pour un Bearer token, vous pouvez
stocker le token dans une variable d’environnement et l’injecter automatiquement. Pour OAuth2, Postman
propose des flux (authorization code, client credentials) selon votre serveur. Pour les clés API, évitez de les
commiter : utilisez des environnements locaux et des secrets vault quand c’est possible.
Points clés
Utilisez HTTPS et ne partagez pas un token en clair.
Nommez clairement vos variables : token_dev, token_staging.
Renouvelez/rafraîchissez : scripts pour automatiser le login.

4. Tests automatiques avec JavaScript
L’onglet Tests permet d’écrire des assertions en JavaScript pour vérifier automatiquement une réponse. Vous
pouvez contrôler le code de statut, la présence d’un champ, le type d’une valeur, ou la structure JSON. Ces
tests transforment Postman en mini-framework de validation : chaque exécution signale immédiatement une
régression. En combinant tests et variables, vous pouvez chaîner des scénarios complets de bout en bout.
Points clés
Vérifiez status, temps de réponse, schéma JSON.
Sauvegardez des valeurs : pm.environment.set('id', ...).
Utilisez des assertions claires et des messages explicites.

5. Scripts Pre-request : préparer la requête
Les scripts Pre-request s’exécutent avant l’envoi de la requête. Ils servent à générer des données dynamiques
(timestamp, nonce), signer une requête, ou récupérer un token. C’est utile quand l’API attend des paramètres
variables à chaque appel, ou lorsqu’on veut éviter de modifier manuellement le body. Une bonne pratique est
de centraliser ces scripts au niveau de la collection pour éviter la duplication.
Points clés
Générez des identifiants : UUID, date ISO, aléatoire contrôlé.
Préparez les headers : Authorization, Content-Type.
Factorisez au niveau collection : cohérence et maintenance.

6. Variables et portée : collection, environnement, global
Postman propose plusieurs niveaux de variables, et la portée est importante. Les variables d’environnement
changent selon la cible (dev/staging/prod). Les variables de collection sont pratiques pour partager une
logique commune entre requêtes. Les variables globales sont à utiliser avec prudence car elles peuvent créer
des effets de bord entre projets. Une discipline simple évite des bugs difficiles à reproduire.
Points clés
Préférez : environnement pour secrets et URLs.
Utilisez : collection pour constantes partagées (v1, chemins).
Évitez : global si vous travaillez sur plusieurs APIs.

7. Importer une spécification OpenAPI
Si votre API est décrite en OpenAPI, Postman peut importer la spécification pour générer automatiquement une
collection de requêtes. Cela accélère la mise en place des tests et réduit les oublis d’endpoints. Cependant,
une génération automatique n’est qu’un point de départ : il faut ensuite ajouter des scénarios réalistes, des
variables, et des tests. Gardez l’import synchronisé avec les versions de votre spec.
Points clés
Import = gain de temps, mais nécessite une finition.
Ajoutez des exemples de body et des assertions par endpoint.
Mettez à jour lors des changements de spec (changelog).

8. Newman : exécuter les collections en CI/CD
Newman est le runner en ligne de commande de Postman. Il permet d’exécuter vos collections
automatiquement dans un pipeline CI/CD, par exemple à chaque pull request ou déploiement. C’est une
manière simple d’introduire des tests de contrat et de non-régression sans écrire tout un framework. En sortie,
Newman fournit des rapports qui aident à diagnostiquer rapidement les échecs.
Points clés
Exécutez sur staging avant promotion en production.
Générez des rapports (HTML/JUnit) pour vos outils CI.
Couplez avec données de test stables pour des résultats fiables.

9. Bonnes pratiques de qualité et lisibilité
Un workspace Postman propre est un vrai livrable d’équipe. Nommez clairement les dossiers et requêtes,
utilisez des descriptions, et standardisez les variables. Ajoutez des tests minimum sur chaque endpoint critique
: statut, schéma, règles métier essentielles. Pour éviter les faux positifs, utilisez des données de test
contrôlées et isolez vos environnements. La qualité vient de la répétabilité.
Points clés
Structure : Auth / Users / Orders / Admin / Health.
Documentez : prérequis, exemples, cas limites.
Stabilisez : jeux de données et nettoyage après tests.

10. Checklist de livraison d’une collection Postman
Avant de partager une collection, vérifiez qu’elle est utilisable par un collègue sans contexte implicite. Toutes
les variables doivent être définies, les environnements fournis, et les scripts documentés. Ajoutez une requête
de santé (health check) et un scénario happy path complet. Enfin, exportez la collection et testez-la sur une
machine différente : c’est le meilleur moyen de détecter les dépendances cachées.
Points clés
README dans la collection : comment démarrer en 2 minutes.
Aucune valeur sensible en dur : tokens, secrets, clés.
Scénario complet : login -> action -> vérification -> cleanup.

Presentations_API_Professionnelles_FR_v2.pdf

Contenu connexe

Similaire à Presentations_API_Professionnelles_FR_v2.pdf

Presentations_API_Professionnelles_FR_v2.pdf