REST et APIs

#REST et APIsCopier le lien

Concevoir une API, c’est définir des ressources stables, des sémantiques claires et des erreurs prévisibles. Au‑delà des verbes, expliquez pourquoi chaque choix existe (idempotence, versionnement, pagination) et comment l’appliquer dans votre contexte.

Objectifs d’apprentissage

• Définir des ressources cohérentes, statuts précis, et gérer l’idempotence.
• Documenter erreurs (format stable), pagination, filtrage, tri.
• Connaître versionnement et sécurité (auth, rate‑limit, CORS de surface).

#Principes RESTCopier le lien

Les ressources exposent des « choses » (users, posts) via des URLs stables (/users/42). Évitez d’encoder des verbes dans les chemins. Les représentations se négocient par Accept/Content-Type avec application/json en pratique. Le serveur contrôle la forme; le client exprime une préférence. REST reste stateless: chaque requête porte le contexte nécessaire (auth, locale) sans dépendre d’un état implicite côté serveur. Côté méthodes, GET est sûr et idempotent, POST sert aux créations et actions non idempotentes, PUT remplace une ressource entière, PATCH la modifie partiellement, DELETE est idempotent.

#Bonnes pratiques (avec pourquoi/comment)Copier le lien

Des chemins cohérents (pluriels /users, hiérarchies /posts/123/comments) aident la lisibilité et le contrôle d’accès. La pagination par offset (limit/offset) est simple mais se fragilise quand les données bougent; la pagination par curseur (keyset) reste stable, surtout combinée à un tri déterministe. Le filtrage et le tri sont explicites (?status=active&sort=-createdAt) et validés; refuser les filtres inconnus évite les surprises et les requêtes lentes. L’idempotence permet aux clients de rejouer sans crainte: GET/PUT/DELETE sont idempotents; pour les POST, une idempotency‑key permet de rendre la création idempotente. Les codes doivent être précis: 201 avec Location pour une création, 204 pour une action sans corps, 409 pour un conflit métier, 422 pour une entité invalide, 429 pour un dépassement de limites.

1{"type":"https://errors.example/validation","title":"Validation failed","status":422,"traceId":"...","errors":[...]}

#ExemplesCopier le lien

1GET /api/users?search=ana2200 OK3{"items":[{"id":1,"name":"Ana"}],"total":1}4 5POST /api/users6{"name":"Ada"}7201 Created8Location: /api/users/2

#OpenAPI minimal (documentation vivante)Copier le lien

Une spec succincte consolide le contrat et alimente la génération de clients.

1openapi: 3.0.32info:3  title: Mini API4  version: 1.0.05paths:6  /users:7    post:8      summary: Créer un utilisateur9      requestBody:10        required: true11        content:12          application/json:13            schema:14              type: object

#AlternativesCopier le lien

• GraphQL: schéma typé, requêtes flexibles; attention au caching et à la complexité.
• gRPC: proto + HTTP/2, efficaces pour services internes.

#Sécurité et limitesCopier le lien

L’authentification utilise souvent des jetons Bearer (JWT/OAuth2) dans Authorization; la portée doit être minimale et les expirations raisonnables. Le rate‑limit se rend visible via RateLimit-Limit, RateLimit-Remaining, Retry-After et des réponses 429 structurées. Côté CORS, autorisez des origines précises et ne combinez jamais * avec des credentials. La validation refuse tôt avec des messages clairs sans divulguer de détails sensibles; chaque erreur porte un traceId pour l’investigation.

#VersionnementCopier le lien

• Chemin (/v1/), sous‑domaine (v1.api.example.com) ou en‑tête (ex.: Accept: application/vnd.example.v1+json).
• Stratégie: conserver des versions stables, déprécier avec préavis; éviter les ruptures silencieuses.

#Mini‑quizCopier le lien

#Animation: cycle d’une requête RESTCopier le lien

#Diagramme: erreur de validation (422, Problem Details)Copier le lien

#Animation: décisions de designCopier le lien

Mini‑exercice: concevez les endpoints et statuts pour « activer/désactiver » un utilisateur. Comparez POST /users/42/disable (action) vs PATCH /users/42 {"active": false} (état). Discutez idempotence et codes de réponse.