Qu'est-ce qu'une API REST? Un Guide Pratique pour les Ingénieurs QA

Les API REST communiquent via HTTP avec des requêtes et des réponses. Un client envoie une méthode, une URL, des en-têtes et un corps optionnel, et le serveur retourne un code de statut et des données.

Le concept central : requête et réponse

Une API (Application Programming Interface) est un moyen pour deux logiciels de communiquer entre eux. Une API REST est un style d'API spécifique qui utilise HTTP, le même protocole que ton navigateur utilise pour charger des sites web.

La conversation suit toujours le même schéma :

1. Ton code (ou test) envoie une requête

2. Le serveur la traite et renvoie une réponse

C'est tout. Le reste, ce sont des détails sur la façon dont ces deux éléments sont structurés.

Anatomie d'une requête HTTP

Chaque requête comporte quatre parties :

1. Méthode (le verbe)

La méthode indique au serveur ce que tu veux faire :

| Méthode | Ce qu'elle fait | Comme dire |

|---|---|---|

| GET | Récupérer des données | "Donne-moi cet élément" |

| POST | Créer quelque chose de nouveau | "Voici de nouvelles données, sauvegarde-les" |

| PUT | Remplacer complètement | "Remplace ça par ma nouvelle version" |

| PATCH | Mettre à jour partiellement | "Change juste ce champ" |

| DELETE | Supprimer | "Supprime ça" |

Un endpoint de rapport de bug pourrait fonctionner ainsi :

• GET /bugs → lister tous les bugs
• GET /bugs/42 → obtenir le bug #42
• POST /bugs → créer un nouveau bug
• PATCH /bugs/42 → mettre à jour le statut du bug #42
• DELETE /bugs/42 → supprimer le bug #42

2. URL (l'adresse)

L'URL indique au serveur sur quoi tu travailles :

https://api.becomeqa.com/v1/users/123/orders

Décortiquons cela :

• https://api.becomeqa.com : le serveur
• /v1 : version de l'API (courant, pas toujours présent)
• /users/123 : l'utilisateur spécifique avec l'ID 123
• /orders : ses commandes

Les parties après le domaine s'appellent le chemin (path). Les nombres et IDs dans le chemin (comme 123) s'appellent des paramètres de chemin.

Parfois les données passent dans l'URL comme paramètres de requête :

GET /users?role=admin&active=true&page=2

La partie ?role=admin&active=true&page=2 filtre et pagine les résultats sans changer la ressource dont on parle.

3. En-têtes

Les en-têtes sont des métadonnées envoyées avec la requête. On ne les voit pas normalement dans le navigateur (ils sont dans l'onglet Network). Les plus courants :

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

4. Corps

Les requêtes POST, PUT et PATCH incluent généralement un corps, les données réelles envoyées. Les API REST utilisent presque toujours JSON :

{
  "title": "Bouton de connexion ne fonctionne pas sur mobile",
  "severity": "high",
  "steps": ["Ouvrir l'app sur mobile", "Appuyer sur Connexion", "Rien ne se passe"]
}

Les requêtes GET et DELETE n'ont généralement pas de corps.

Anatomie d'une réponse HTTP

Le serveur répond avec :

1. Code de statut

Un nombre à 3 chiffres qui indique ce qui s'est passé :

| Plage | Catégorie | Signification |

|---|---|---|

| 2xx | Succès | La requête a fonctionné |

| 3xx | Redirection | La ressource a été déplacée, va là |

| 4xx | Erreur client | Ta requête est incorrecte |

| 5xx | Erreur serveur | Le serveur a planté |

Les codes les plus importants pour les tests :

| Code | Nom | Quand il apparaît |

|---|---|---|

| 200 | OK | Succès standard pour GET |

| 201 | Created | POST qui a créé quelque chose |

| 204 | No Content | Succès mais rien à retourner (DELETE) |

| 400 | Bad Request | Saisie invalide (champ manquant, mauvais format) |

| 401 | Unauthorized | Non authentifié (token absent ou invalide) |

| 403 | Forbidden | Authentifié mais non autorisé |

| 404 | Not Found | La ressource n'existe pas |

| 422 | Unprocessable Entity | JSON valide mais échec de validation |

| 429 | Too Many Requests | Limite de débit atteinte |

| 500 | Internal Server Error | Crash backend non géré |

| 503 | Service Unavailable | Serveur hors ligne ou surchargé |

2. En-têtes de réponse

Similaires aux en-têtes de requête, des métadonnées sur la réponse :

Content-Type: application/json
X-Request-Id: abc-123-def
Cache-Control: no-cache

3. Corps de la réponse

Les données réelles retournées, généralement en JSON :

{
  "id": 42,
  "title": "Bouton de connexion ne fonctionne pas sur mobile",
  "severity": "high",
  "status": "open",
  "created_at": "2026-05-17T10:30:00Z"
}

Ou une erreur :

{
  "error": "validation_failed",
  "message": "Le titre est requis",
  "field": "title"
}

Authentification : comment les API savent qui tu es

La plupart des API requièrent une authentification. Deux approches principales :

Bearer Token / JWT

Après la connexion, le serveur te donne un token, une longue chaîne qui prouve ton identité. Tu l'inclus dans chaque requête suivante :

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIn0.abc123

Le serveur valide le token sans avoir besoin de rechercher ta session en base de données. Les tokens expirent (généralement entre 15 minutes et 24 heures).

Sessions basées sur les cookies

Ancien pattern. Après la connexion, le serveur définit un cookie. Le navigateur l'envoie automatiquement avec chaque requête à ce domaine. Tu ne le vois pas dans le corps de la requête, le navigateur gère ça.

Clés API

Utilisées pour la communication serveur à serveur. Une clé statique dans l'en-tête :

X-API-Key: sk-1234567890abcdef

Comment inspecter les appels API dans un navigateur

Ouvre les DevTools → onglet Network → filtre par "Fetch/XHR". Chaque appel API fait par ton application apparaîtra ici.

Clique sur n'importe quelle requête pour voir :

• Onglet Headers : en-têtes de requête, URL, méthode
• Onglet Payload : corps de la requête
• Onglet Response : ce que le serveur a retourné
• Code de statut : dans la vue liste, la colonne numérique

C'est là qu'on débogue "est-ce un bug frontend ou backend ?" Si l'interface affiche des données incorrectes, vérifie ce que l'API a réellement retourné. Si l'API a retourné les bonnes données et que l'interface les affiche mal, c'est frontend. Si l'API a retourné de mauvaises données, c'est backend.

Tester les API : ce qu'il faut vérifier

Lors du test d'un endpoint API (manuellement ou avec Playwright), vérifie :

Le code de statut correspond à l'attendu

• Créer une ressource → 201, pas 200
• Obtenir une ressource → 200
• Suppression réussie sans contenu → 204
• Saisie invalide → 400 ou 422, pas 500

Le corps de la réponse est correct

• Les champs requis sont présents
• Les types de données sont corrects ("age": 25 et non "age": "25")
• Les valeurs correspondent à ce qui a été envoyé
• Aucune donnée sensible n'est exposée (mots de passe, IDs internes)

Les réponses d'erreur sont utiles

Les erreurs 400 doivent expliquer ce qui était invalide, et les erreurs 404 doivent confirmer que la ressource n'existe pas. Les erreurs 401 ne doivent pas révéler d'informations sensibles à la sécurité.

Les cas limites se comportent correctement

• Liste vide : retourne [] et non null
• ID inexistant : retourne 404 et non 500
• Corps JSON invalide : retourne 400 et non 500
• Action non autorisée : retourne 403 et non 200 avec un corps vide

Les API REST dans Playwright

Playwright peut faire des requêtes HTTP directement, sans navigateur :

test('créer un utilisateur retourne 201', async ({ request }) => {
  const response = await request.post('https://api.becomeqa.com/users', {
    data: {
      name: 'Test User',
      email: 'test@example.com',
      role: 'member',
    },
  });

  expect(response.status()).toBe(201);

  const body = await response.json();
  expect(body.id).toBeTruthy();
  expect(body.email).toBe('test@example.com');
  expect(body).not.toHaveProperty('password'); // pas de fuite
});

On peut aussi intercepter les appels API faits par le navigateur pendant les tests E2E :

test('gère l\'erreur API correctement', async ({ page }) => {
  // Forcer l'API à retourner une erreur
  await page.route('**/api/users', (route) => {
    route.fulfill({ status: 500, body: JSON.stringify({ error: 'server error' }) });
  });

  await page.goto('/users');

  // L'application doit afficher un état d'erreur, pas planter
  await expect(page.locator('[data-testid="error-banner"]')).toBeVisible();
});

Résumé du vocabulaire clé

| Terme | Signification |

|---|---|

| API | Interface pour la communication entre logiciels |

| REST | Un style d'API qui utilise HTTP |

| Endpoint | Une combinaison URL + méthode spécifique (GET /users) |

| Requête | Ce que tu envoies au serveur |

| Réponse | Ce que le serveur renvoie |

| Code de statut | Nombre à 3 chiffres indiquant le succès ou l'échec |

| JSON | Le format de données utilisé par les API REST |

| En-tête | Métadonnées attachées à une requête ou réponse |

| Corps | Les données réelles dans une requête ou réponse |

| Bearer token | Credential envoyé dans l'en-tête Authorization |

| Paramètre de chemin | Partie variable de l'URL (/users/123, où 123 est le param) |

| Paramètre de requête | Filtres dans l'URL après ? (?page=2&sort=asc) |

Comprendre les API REST fait de toi un ingénieur QA considérablement meilleur. Tu peux lire le trafic réseau et diagnostiquer si un bug est frontend ou backend. Tu peux aussi écrire des tests au niveau API, 100 fois plus rapides que les tests navigateur, et parler bien plus efficacement aux développeurs quand tu signales des bugs.