Qu'est-ce que REST ?

REST (Representational State Transfer) est un style architectural pour la construction de systèmes distribués, proposé par Roy Fielding en 2000 dans sa thèse de doctorat. REST n'est pas un protocole ou une norme, mais plutôt un ensemble de principes et de contraintes que le système doit respecter.

API (Application Programming Interface) est une interface pour l'interaction entre les programmes. L'API REST, respectivement, est une API construite selon les principes REST.

En termes simples, l'API REST est un moyen d'organiser la communication entre le client et le serveur via le protocole HTTP, où chaque ressource (données) a une adresse unique (URL) et peut être consultée à l'aide de méthodes HTTP standard.

🔥 100 000+ étudiants déjà avec nous

Marre de lire la théorie ?
Il est temps de coder !

Kodik — une appli où tu apprends à coder par la pratique. Mentor IA, leçons interactives, projets réels.

Ont rejoint aujourd'hui

Кодик

Principes de base de REST

REST est basé sur six principes clés qui définissent l'architecture du système.

1. Client-Serveur

L'architecture est divisée en un client qui envoie des requêtes et un serveur qui traite ces requêtes et renvoie des réponses. Cette séparation permet au client et au serveur de se développer indépendamment l'un de l'autre.

2. Stateless (sans enregistrement de l'état)

Chaque requête du client au serveur doit contenir toutes les informations nécessaires pour comprendre et traiter la requête. Le serveur ne stocke pas d'informations sur l'état du client entre les requêtes. Si une authentification est requise, un jeton est transmis avec chaque requête.

3. Cacheable (Mise en cache)

Les réponses du serveur doivent indiquer clairement si elles peuvent être mises en cache. Cela améliore les performances du système en réduisant le nombre de requêtes au serveur.

4. Uniform Interface (Interface uniforme)

C'est un principe clé de REST qui simplifie l'architecture du système. Il comprend quatre aspects : l'identification des ressources via l'URI, la manipulation des ressources via des vues, des messages auto-descriptifs et HATEOAS (hypermédia en tant que moteur d'état de l'application).

5. Système en couches

Le client ne peut pas déterminer s'il est connecté directement au serveur final ou à un nœud intermédiaire. Cela vous permet d'ajouter des équilibreurs de charge, des caches et d'autres composants intermédiaires sans modifier le code client.

6. Code on Demand (Code à la demande)

C'est le seul principe facultatif. Les serveurs peuvent étendre temporairement les fonctionnalités du client en envoyant du code exécutable, tel que JavaScript.

Méthodes HTTP dans l'API REST

L'API REST utilise des méthodes HTTP standard pour effectuer des opérations avec des ressources. Chaque méthode a un but spécifique :

GET — Récupération de données

La méthode GET est utilisée pour lire les données du serveur. Elle ne doit pas modifier l'état de la ressource.

// Obtenir la liste de tous les utilisateurs
fetch('https://api.example.com/users')
  .then(response => response.json())
  .then(data => console.log(data));

// Obtenir un utilisateur spécifique
fetch('https://api.example.com/users/123')
  .then(response => response.json())
  .then(data => console.log(data));

POST — Création d'une nouvelle ressource

POST est utilisé pour créer de nouvelles ressources sur le serveur.

fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Ivan Petrov',
    email: 'ivan@example.com'
  })
})
  .then(response => response.json())
  .then(data => console.log(data));

PUT — Mise à jour complète de la ressource

PUT remplace la ressource existante par de nouvelles données.

fetch('https://api.example.com/users/123', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Ivan Petrov',
    email: 'newemail@example.com',
    age: 30
  })
})
  .then(response => response.json())
  .then(data => console.log(data));

PATCH — Mise à jour partielle de la ressource

PATCH ne met à jour que les champs spécifiés de la ressource.

fetch('https://api.example.com/users/123', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'newemail@example.com'
  })
})
  .then(response => response.json())
  .then(data => console.log(data));

DELETE — Suppression de la ressource

DELETE est utilisé pour supprimer une ressource du serveur.

fetch('https://api.example.com/users/123', {
  method: 'DELETE'
})
  .then(response => {
    if (response.ok) {
      console.log('User removed');
    }
  });

Structure de l'API REST

La structure correcte de l'URL dans l'API REST est essentielle pour comprendre et utiliser l'API.

Ressources et collections

Dans REST, tout est une ressource. Les ressources sont regroupées en collections :

GET    /users           - Получить список пользователей (коллекция)
GET    /users/123       - Получить конкретного пользователя (ресурс)
POST   /users           - Создать нового пользователя
PUT    /users/123       - Обновить пользователя
DELETE /users/123       - Удалить пользователя

Ressources intégrées

Pour les ressources liées, les URL imbriquées sont utilisées :

GET    /users/123/posts           - Все посты пользователя
GET    /users/123/posts/456       - Конкретный пост пользователя
POST   /users/123/posts           - Создать пост для пользователя
DELETE /users/123/posts/456       - Удалить пост пользователя

Filtrer et trier

Utilisez les paramètres de requête pour filtrer, trier et paginer :

GET /users?role=admin                    - Фильтрация по роли
GET /users?sort=name&order=asc          - Сортировка по имени
GET /users?page=2&limit=20              - Пагинация
GET /users?search=иван                   - Поиск

Statuts HTTP des réponses

L'API REST utilise des codes d'état HTTP standard pour informer le client du résultat de la requête.

Réponses réussies (2xx)

200 OK — la requête a été exécutée avec succès (pour GET, PUT, PATCH)
201 Created — ressource créée avec succès (pour POST)
204 No Content — la requête a réussi, mais il n'y a pas de contenu à renvoyer (souvent pour DELETE)

Erreurs client (4xx)

400 Bad Request — requête incorrecte (par exemple, JSON invalide)
401 Unauthorized - authentification requise
403 Forbidden - accès interdit (authentification, mais pas de droits)
404 Not Found - ressource non trouvée
409 Conflict — conflit (par exemple, un utilisateur avec cette adresse e-mail existe déjà)
422 Unprocessable Entity — validation non réussie

Erreurs de serveur (5xx)

500 Internal Server Error - erreur interne du serveur
503 Service Unavailable - le service est temporairement indisponible

Format des données

L'API REST fonctionne généralement avec JSON (JavaScript Object Notation), bien que XML puisse également être utilisé.

Exemple de réponse JSON

{
  "id": 123,
  "name": "Ivan Petrov",
  "email": "ivan@example.com",
  "created_at": "2024-01-15T10:30:00Z",
  "posts": [
    {
      "id": 1,
      "title": "First post",
      "published": true
    }
  ]
}

Exemple d'erreur JSON

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Data validation error",
    "details": [
      {
        "field": "email",
        "message": "Incorrect email format"
      }
    ]
  }
}

Authentification et sécurité

L'API REST nécessite souvent une authentification pour accéder aux ressources sécurisées.

JWT (JSON Web Token)

La méthode d'authentification la plus populaire pour l'API REST :

// Obtenir un jeton lors de la connexion
fetch('https://api.example.com/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
})
  .then(response => response.json())
  .then(data => {
    // Enregistrer le jeton
    localStorage.setItem('token', data.token);
  });

// Utilisation d'un jeton pour les requêtes sécurisées
fetch('https://api.example.com/users/me', {
  headers: {
    'Authorization': `Bearer ${localStorage.getItem('token')}`
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

API Keys

Méthode simple pour les API orientées services :

fetch('https://api.example.com/data', {
  headers: {
    'X-API-Key': 'your-secret-key'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Version de l'API

Au fur et à mesure que l'API évolue, il est important de maintenir la rétrocompatibilité. Il existe plusieurs approches de gestion des versions :

URL Path Versioning

https://api.example.com/v1/users
https://api.example.com/v2/users

Header Versioning

fetch('https://api.example.com/users', {
  headers: {
    'Accept': 'application/vnd.example.v2+json'
  }
})

Query Parameter Versioning

https://api.example.com/users?version=2

Exemple pratique : créer une API REST simple sur Node.js

Créons une API REST simple pour gérer la liste des tâches.

const express = require('express');
const app = express();

app.use(express.json());

// Stockage temporaire des données
let tasks = [
  { id: 1, title: 'Explore the REST API', completed: false },
  { id: 2, title: 'Create a project', completed: false }
];

let nextId = 3;

// GET - Obtenir toutes les tâches
app.get('/api/tasks', (req, res) => {
  res.json(tasks);
});

// GET - Obtenir une tâche spécifique
app.get('/api/tasks/:id', (req, res) => {
  const task = tasks.find(t => t.id === parseInt(req.params.id));
  
  if (!task) {
    return res.status(404).json({ 
      error: 'Task not found' 
    });
  }
  
  res.json(task);
});

// POST - Créer une nouvelle tâche
app.post('/api/tasks', (req, res) => {
  const { title } = req.body;
  
  if (!title) {
    return res.status(400).json({ 
      error: 'Task name is required' 
    });
  }
  
  const newTask = {
    id: nextId++,
    title,
    completed: false
  };
  
  tasks.push(newTask);
  res.status(201).json(newTask);
});

// PUT - Mettre à jour la tâche
app.put('/api/tasks/:id', (req, res) => {
  const taskIndex = tasks.findIndex(t => t.id === parseInt(req.params.id));
  
  if (taskIndex === -1) {
    return res.status(404).json({ 
      error: 'Task not found' 
    });
  }
  
  const { title, completed } = req.body;
  
  tasks[taskIndex] = {
    id: parseInt(req.params.id),
    title: title || tasks[taskIndex].title,
    completed: completed !== undefined ? completed : tasks[taskIndex].completed
  };
  
  res.json(tasks[taskIndex]);
});

// DELETE - Supprimer la tâche
app.delete('/api/tasks/:id', (req, res) => {
  const taskIndex = tasks.findIndex(t => t.id === parseInt(req.params.id));
  
  if (taskIndex === -1) {
    return res.status(404).json({ 
      error: 'Task not found' 
    });
  }
  
  tasks.splice(taskIndex, 1);
  res.status(204).send();
});

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Meilleures pratiques lors du développement de l'API REST

1. Utilisez des noms, pas des verbes

Bien :

GET /users
POST /users

Mauvais :

GET /getUsers
POST /createUser

2. Utilisez le pluriel pour les collections

GET /users (а не /user)
GET /posts (а не /post)

3. Retournez les bons codes HTTP

Ne renvoyez pas 200 OK pour toutes les réponses. Utilisez les codes d'état appropriés.

4. Fournissez des messages d'erreur détaillés

{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Invalid email address provided",
    "field": "email",
    "value": "invalid-email"
  }
}

5. Utilisez la pagination pour les grandes collections

app.get('/api/users', (req, res) => {
  const page = parseInt(req.query.page) || 1;
  const limit = parseInt(req.query.limit) || 10;
  const startIndex = (page - 1) * limit;
  const endIndex = page * limit;

  const results = {
    data: users.slice(startIndex, endIndex),
    pagination: {
      page,
      limit,
      total: users.length,
      totalPages: Math.ceil(users.length / limit)
    }
  };

  res.json(results);
});

6. Documentez votre API

Utilisez des outils tels que Swagger/OpenAPI pour documenter l'API.

7. Utilisez HTTPS

Utilisez toujours HTTPS pour le transfert de données, en particulier lorsque vous travaillez avec des informations sensibles.

8. Mettre en œuvre la limitation de débit

Limitez le nombre de demandes d'un client pour vous protéger contre les abus.

REST vs GraphQL vs gRPC

REST n'est pas la seule façon de construire une API. Voici une brève comparaison :

REST convient à la plupart des applications Web standard, est facile à comprendre et à mettre en œuvre, dispose d'un large support et d'une excellente mise en cache.

GraphQL utile lorsque le client a besoin de flexibilité dans le choix des données, permet d'obtenir tout en une seule requête et d'éviter la sur-récupération ou la sous-récupération de données.

gRPC optimal pour l'architecture de microservices, les systèmes hautes performances et les API internes, utilise un protocole binaire et est plus rapide que REST.

Outils pour travailler avec l'API REST

Test de l'API

Postman — un outil populaire pour tester les API avec une interface graphique
Insomnia — une alternative à Postman avec une interface minimaliste
curl — utilitaire de console pour les requêtes HTTP

# Exemple d'utilisation de curl
curl -X GET https://api.example.com/users
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Ivan","email":"ivan@example.com"}'

Bibliothèques clientes

JavaScript/TypeScript:

Fetch API (intégré)
Axios
Got

Python:

requests
httpx

PHP:

Guzzle
cURL

Conclusion

L'API REST est une technologie fondamentale du développement Web moderne qui fournit un moyen simple et standardisé d'interaction entre le client et le serveur. Comprendre les principes REST, utiliser correctement les méthodes HTTP et les codes d'état, et suivre les meilleures pratiques vous aidera à créer des API de haute qualité, évolutives et faciles à maintenir.

Commencez par des projets simples, en ajoutant progressivement de la complexité, et n'oubliez pas la documentation et les tests. L'API REST est une compétence qui restera pertinente pendant de nombreuses années et vous ouvrira les portes du monde du développement moderne.

Rejoignez la plateforme éducative Code, où vous trouverez des cours structurés sur JavaScript, Node.js, Python et d'autres technologies modernes.

Notre communauté amicale de développeurs à Telegram toujours prêt à vous aider avec des questions, à partager son expérience et à vous soutenir sur la voie pour devenir un programmeur professionnel !

API REST : Guide complet pour les développeurs