Slide 1

Les APIs REST

Formation DWWM - Symfony 6.4

Slide 2

Qu'est-ce qu'une API ?

Application Programming Interface

Une API est un contrat qui définit comment deux applications peuvent communiquer entre elles.

💡 Analogie du restaurant

Imaginez un restaurant : vous (le client) ne pouvez pas aller directement en cuisine. Le serveur fait l'interface entre vous et la cuisine. Il prend votre commande, la transmet au chef, puis vous apporte le plat.

L'API, c'est le serveur !

👨‍💼 Explication : Cette analogie aide à comprendre que l'API cache la complexité interne tout en exposant seulement ce qui est nécessaire.

Dans le développement web :

• Frontend (React, Vue, Angular) = Le client du restaurant

• API = Le serveur

• Backend/Base de données = La cuisine

🔍 Point clé : L'API permet au frontend de récupérer des données sans connaître la structure de la base de données.

Slide 3

Pourquoi utiliser des APIs ?

🎯 Objectif : Comprendre les bénéfices business et techniques des APIs

✅ Avantages

• Séparation des responsabilités

• Réutilisabilité : Une API pour plusieurs clients

• Évolutivité : Modifier le backend sans casser le frontend

• Collaboration : Équipes frontend/backend indépendantes

• Multi-plateforme : Web, mobile, desktop

⚠️ Défis

• Complexité de mise en place

• Sécurité à prévoir

• Documentation indispensable

• Gestion des versions

• Performance réseau

💼 Exemple concret :

Une entreprise e-commerce avec une API peut avoir :

• Un site web (React)

• Une application mobile (React Native)

• Un back-office administrateur (Vue.js)

• Des intégrations partenaires

→ Toutes ces applications utilisent la même API !

Slide 4

REST : REpresentational State Transfer

Un style architectural pour les APIs

REST n'est pas un protocole ou une technologie, mais un ensemble de principes pour concevoir des APIs web efficaces.

📚 Note : REST a été défini en 2000 par Roy Fielding dans sa thèse de doctorat

🎯 Principe fondamental

Tout dans votre application est considéré comme une "ressource" accessible via une URL unique.

💡 Astuce : Pensez "nom" plutôt que "verbe" dans vos URLs

Exemples de ressources :

• Un utilisateur : /users/123

• Une liste d'articles : /articles

• Un article spécifique : /articles/456

• Les commentaires d'un article : /articles/456/comments

🔍 Remarque : Chaque URL représente une "chose" de votre domaine métier

❌ Anti-patterns à éviter :

• /getUser?id=123 (verbe dans l'URL)

• /user_list (underscores)

• /api/users/delete/123 (action dans l'URL)

→ Utilisez les méthodes HTTP à la place !

Slide 5

Les méthodes HTTP dans REST

REST utilise les verbes HTTP pour définir les actions à effectuer sur les ressources.

🎭 Analogie : Les méthodes HTTP sont comme des verbes d'action dans une phrase

GET

Récupérer une ressource

Lecture seule, sans effet de bord

POST

Créer une nouvelle ressource

Envoi de données au serveur

PUT

Modifier complètement une ressource

Remplacement total

PATCH

Modifier partiellement une ressource

Mise à jour partielle

DELETE

Supprimer une ressource

Suppression définitive

🔄 Propriétés importantes :

• GET, PUT, DELETE sont idempotents (même résultat si répétés)

• GET est safe (ne modifie rien)

• POST n'est ni safe, ni idempotent

💭 Réflexion : Pourquoi ces propriétés sont-elles importantes pour les APIs ?

Slide 6

Exemples concrets d'API REST

Gestion d'utilisateurs

🎯 Scénario : API pour un système de gestion d'utilisateurs

GET /api/users           → Récupérer tous les utilisateurs
GET /api/users/123       → Récupérer l'utilisateur ID 123
POST /api/users          → Créer un nouvel utilisateur
PUT /api/users/123       → Modifier complètement l'utilisateur 123
PATCH /api/users/123     → Modifier partiellement l'utilisateur 123
DELETE /api/users/123    → Supprimer l'utilisateur 123

Exemple de requête POST :

👨‍💻 Cas d'usage : Inscription d'un nouvel utilisateur

POST /api/users
Content-Type: application/json

{
  "name": "Jean Dupont",
  "email": "jean@example.com",
  "role": "user"
}

Exemple de réponse :

✅ Succès : L'utilisateur a été créé avec un ID auto-généré

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 124,
  "name": "Jean Dupont",
  "email": "jean@example.com",
  "role": "user",
  "created_at": "2024-01-15T10:30:00Z"
}

🔍 Points à noter :

• 201 Created : Code spécifique pour les créations

• ID auto-généré : Ajouté par le serveur

• Timestamp : Date de création automatique

• Content-Type : Toujours préciser le format

Slide 7

Les codes de statut HTTP

Les APIs REST utilisent les codes de statut HTTP pour indiquer le résultat d'une requête.

💬 Communication : Les codes de statut sont le langage universel du web

2xx - Succès

200 OK, 201 Created

3xx - Redirection

301 Moved, 304 Not Modified

4xx - Erreur client

400 Bad Request, 404 Not Found

5xx - Erreur serveur

500 Internal Error

🔍 Codes les plus courants :

• 200 OK : Requête réussie (GET, PUT, PATCH)

• 201 Created : Ressource créée avec succès (POST)

• 204 No Content : Succès sans contenu (DELETE)

• 400 Bad Request : Données invalides

• 401 Unauthorized : Authentification requise

• 403 Forbidden : Accès interdit

• 404 Not Found : Ressource introuvable

• 500 Internal Server Error : Erreur du serveur

🎯 Bonnes pratiques :

• Toujours renvoyer le bon code : Ne pas tout mettre en 200

• Messages d'erreur explicites : Aider le développeur client

• Cohérence : Même logique dans toute l'API

💡 Astuce : Les codes de statut permettent un debugging rapide

Slide 8

Les 6 principes de REST

📐 Architecture : Ces contraintes garantissent une API robuste et scalable

1. 🏗️ Architecture client-serveur

Séparation claire entre le client et le serveur.

→ Permet l'évolution indépendante des deux parties

2. 🔄 Sans état (Stateless)

Chaque requête contient toutes les informations nécessaires.

→ Le serveur ne stocke pas de contexte entre les requêtes

3. 💾 Mise en cache

Les réponses peuvent être mises en cache pour améliorer les performances.

→ Headers Cache-Control, ETag, Last-Modified

4. 🔗 Interface uniforme

Utilisation cohérente des URLs et des méthodes HTTP.

→ Facilite la compréhension et l'utilisation de l'API

5. 📦 Système en couches

L'architecture peut comporter plusieurs couches (proxies, load balancers...).

→ Transparent pour le client

6. 📝 Code à la demande (optionnel)

Le serveur peut envoyer du code exécutable au client.

→ Rare en pratique, ex: JavaScript dans les navigateurs

🎯 En résumé :

Une API qui respecte ces principes sera scalable, maintenable et performante.

Slide 9

Format des données : JSON

Les APIs REST modernes utilisent principalement le format JSON (JavaScript Object Notation).

📊 Standard : JSON a remplacé XML grâce à sa simplicité

📋 Pourquoi JSON ?

• Léger et facile à lire

• Support natif dans la plupart des langages

• Structure claire et flexible

• Standard web

💡 Bonus : Lisible par les humains et les machines

Exemple de réponse JSON :

📝 Cas d'usage : Liste d'utilisateurs avec pagination

{
  "users": [
    {
      "id": 1,
      "name": "Alice Martin",
      "email": "alice@example.com",
      "profile": {
        "age": 28,
        "city": "Paris"
      },
      "roles": ["user", "admin"]
    },
    {
      "id": 2,
      "name": "Bob Durand",
      "email": "bob@example.com",
      "profile": {
        "age": 32,
        "city": "Lyon"
      },
      "roles": ["user"]
    }
  ],
  "total": 2,
  "page": 1
}

🔍 Structure analysée :

• Données principales : tableau "users"

• Métadonnées : "total", "page" pour la pagination

• Objets imbriqués : "profile" pour grouper des infos

• Tableaux : "roles" pour les données multiples

🎯 Pattern courant : Données + métadonnées

Slide 10

Bonnes pratiques API REST

✅ Guide : Ces pratiques garantissent une API professionnelle

🎯 URLs et nommage

✅ Bien : /api/users, /api/articles/123/comments

❌ Éviter : /api/getUsers, /api/user_list

💡 Règle : Noms au pluriel, hiérarchie logique

📝 Versioning

• Dans l'URL : /api/v1/users

• Dans les headers : Accept: application/vnd.api+json;version=1

🔄 Stratégie : Planifier dès le début

🔒 Sécurité

• HTTPS toujours (même en développement)

• Authentification (JWT, OAuth2)

• Validation stricte des données

• Rate limiting pour éviter les abus

🛡️ Principe : Sécurité par conception

📚 Documentation

• OpenAPI/Swagger pour la documentation interactive

• Exemples de requêtes/réponses complets

• Codes d'erreur explicites avec solutions

• Guides d'utilisation par cas d'usage

📖 Objectif : Développeur autonome en 5 minutes

Slide 11

API REST avec Symfony 6.4

Outils Symfony pour les APIs

🔧 Symfony offre un écosystème complet pour créer des APIs professionnelles

🔧 Composants essentiels :

• Serializer : Conversion objet ↔ JSON

• Validator : Validation des données

• Security : Authentification et autorisation

• Routing : Gestion des routes API

💡 Ces composants s'intègrent parfaitement ensemble

📦 API Platform (recommandé)

API Platform est un framework Symfony spécialisé pour créer des APIs REST et GraphQL rapidement.

• Génération automatique des endpoints

• Documentation OpenAPI automatique

• Interface d'administration web

• Filtres et pagination intégrés

• Validation automatique

🚀 Gain de temps : 80% de code en moins !

⚡ Installation :

composer require api-platform/core

🎯 Choix de l'approche :

• API Platform : Projet nouveau, développement rapide

• Controllers manuels : Contrôle total, logique métier complexe

• Hybride : API Platform + controllers custom

Slide 12

Exemple : Controller API Symfony

👨‍💻 Exemple pratique : Controller REST pour la gestion d'utilisateurs

// src/Controller/ApiUserController.php

namespace App\Controller;

use App\Entity\User;
use App\Repository\UserRepository;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Annotation\Route;

#[Route('/api/users', name: 'api_users_')]
class ApiUserController extends AbstractController
{
    #[Route('', name: 'index', methods: ['GET'])]
    public function index(UserRepository $userRepository): JsonResponse
    {
        $users = $userRepository->findAll();
        
        return $this->json($users, 200, [], [
            'groups' => ['user:read']
        ]);
    }

    #[Route('/{id}', name: 'show', methods: ['GET'])]
    public function show(User $user): JsonResponse
    {
        return $this->json($user, 200, [], [
            'groups' => ['user:read']
        ]);
    }
}

🔍 Points clés du code :

• Attributes PHP 8 : #[Route] pour définir les routes

• Injection de dépendance : UserRepository injecté automatiquement

• Serialization groups : 'user:read' pour contrôler les données exposées

• JsonResponse : Réponse JSON automatique

• ParamConverter : User $user converti automatiquement depuis l'ID

💭 Exercice de réflexion :

• Comment ajouter une méthode POST pour créer un utilisateur ?

• Que manque-t-il pour avoir un CRUD complet ?

• Comment gérer la validation des données ?

Slide 13

À retenir

🎯 Points clés :

• Une API REST est une interface standardisée pour faire communiquer des applications

• Elle utilise les méthodes HTTP (GET, POST, PUT, DELETE) sur des ressources

• Le format JSON est le standard pour échanger les données

• Symfony 6.4 offre tous les outils pour créer des APIs robustes

• API Platform accélère le développement d'APIs REST

💡 Conseil : Commencez simple, puis enrichissez progressivement

🚀 Prochaines étapes :

1. Pratique : Créer votre première API avec Symfony

2. Sécurité : Authentification JWT et autorisations

3. Tests : Tests d'API avec PHPUnit et fixtures

4. Documentation : OpenAPI et Swagger UI

5. Déploiement : Mise en production et monitoring

📚 Ressources : Documentation Symfony + API Platform

🎓 Pour aller plus loin :

• GraphQL : Alternative moderne à REST

• Microservices : Architecture distribuée

• Event-driven APIs : WebSockets, Server-Sent Events

• API Gateway : Gestion centralisée des APIs

🔮 L'écosystème API évolue constamment !

Slide 14

Questions ?

Des questions sur les APIs REST ?

N'hésitez pas à poser vos questions !

🤔💭