Tester une API : curl, Bruno, Postman et HTTPie

Tester une API, c'est lui envoyer des requêtes et vérifier que chaque réponse respecte le contrat : le bon code de statut, les bons en-têtes, un corps de la bonne forme, et les bons refus quand la requête est invalide ou non autorisée. On teste à la main pendant le développement, avec curl ou un client graphique comme Bruno ou Postman, puis on automatise les tests pour qu'ils tournent à chaque modification. Ce chapitre présente ces outils, ce qu'il faut tester, et comment écrire des tests d'intégration.

Pourquoi le navigateur ne suffit pas

Taper une URL dans la barre d'adresse envoie un GET, sans en-tête Authorization, et c'est tout. Pour envoyer un POST avec un corps JSON, un PATCH, un DELETE ou un jeton, il faut un client HTTP. Il en existe trois familles :

curl, le couteau suisse

curl est installé sur Linux, macOS et Windows 10 et suivants. Les options à connaître :

Les opérations CRUD sur l'API d'AppliFrais, avec le jeton dans une variable :

JETON="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
API="https://api.gsb.example/v1"

# Lire une fiche, en-têtes compris
curl -i "$API/fiches/12" -H "Authorization: Bearer $JETON"

# Lister avec des filtres (guillemets obligatoires à cause du &)
curl -s "$API/fiches?etat=CL&limite=5" -H "Authorization: Bearer $JETON"

# Créer
curl -i --json '{"mois":"2026-11"}' "$API/fiches" -H "Authorization: Bearer $JETON"

# Modifier une partie
curl -i -X PATCH --json '{"etat":"CL"}' "$API/fiches/12" -H "Authorization: Bearer $JETON"

# Supprimer, en n'affichant que le code de statut
curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "$API/fiches/13" -H "Authorization: Bearer $JETON"

La création répond, contre l'API de démonstration (en-têtes Date et Connection omis) :

HTTP/1.1 201 Created
Location: /v1/fiches/13
Content-Type: application/json; charset=utf-8

{"id":13,"visiteurId":7,"mois":"2026-11","etat":"CR","montantValide":null}

Pour lire un gros document JSON, envoie la sortie dans un outil qui l'indente : jq (curl -s … | jq), ou python3 -m json.tool. jq sait aussi extraire une valeur : curl -s … | jq -r '.donnees[0].mois'.

HTTPie, plus lisible

HTTPie est un client en ligne de commande pensé pour les API : la syntaxe est plus courte et la sortie colorée et indentée. champ=valeur construit un corps JSON (les valeurs sont des chaînes ; champ:=valeur envoie un nombre, un booléen ou un tableau), et Nom:valeur ajoute un en-tête.

# GET avec un en-tête
http GET https://api.gsb.example/v1/fiches/12 "Authorization:Bearer $JETON"

# POST JSON : corps {"date":"2026-10-14","libelle":"Taxi gare","montant":18.4}
http POST https://api.gsb.example/v1/fiches/12/frais-hors-forfait \
  "Authorization:Bearer $JETON" date=2026-10-14 libelle="Taxi gare" montant:=18.4

Les clients graphiques : Bruno, Postman et les autres

Un client graphique organise les requêtes en collections, gère des environnements (local, préproduction, production) avec leurs variables, enchaîne des requêtes et exécute des tests sur les réponses.

Pour un projet de BTS, Bruno est un excellent choix : gratuit, sans compte, et la collection de tests de ton API se trouve dans ton dépôt Git, ce qui la rend facile à montrer au jury. Tous ces outils savent importer un document OpenAPI (chapitre 7) et créer une requête par route.

Les variables d'environnement évitent de recopier l'adresse et le jeton dans chaque requête :

URL      : {{baseUrl}}/fiches/12
En-tête  : Authorization: Bearer {{jeton}}

Environnement « local »      : baseUrl = http://localhost:3000/v1
Environnement « préprod »    : baseUrl = https://preprod-api.gsb.example/v1

Un script après la réponse de la requête de connexion enregistre le jeton dans une variable, réutilisée par toutes les autres requêtes :

// Bruno (onglet Script, « post response »)
bru.setEnvVar('jeton', res.getBody().accessToken);

// Postman (onglet Scripts, « post-response »)
pm.environment.set('jeton', pm.response.json().accessToken);

Et des tests vérifient automatiquement chaque réponse :

// Bruno (onglet Tests)
test('crée la fiche avec 201 et Location', function () {
  expect(res.getStatus()).to.equal(201);
  expect(res.getHeader('location')).to.match(/^\/v1\/fiches\/\d+$/);
  expect(res.getBody().etat).to.equal('CR');
});

// Postman (onglet Scripts, « post-response »)
pm.test('crée la fiche avec 201 et Location', () => {
  pm.response.to.have.status(201);
  pm.expect(pm.response.headers.get('Location')).to.match(/^\/v1\/fiches\/\d+$/);
  pm.expect(pm.response.json().etat).to.eql('CR');
});

Une collection entière se lance d'un coup, dans l'interface ou en ligne de commande (bru run pour Bruno, postman collection run ou Newman pour Postman), par exemple dans un pipeline d'intégration continue.

Les fichiers .http

Les fichiers .http décrivent des requêtes en texte brut, presque comme elles circulent sur le réseau. L'extension REST Client de VS Code et les IDE JetBrains affichent un lien « Send Request » au-dessus de chacune :

@baseUrl = http://localhost:3000/v1
@jeton = eyJhbGciOi…

### Lire la fiche 12
GET {{baseUrl}}/fiches/12
Authorization: Bearer {{jeton}}

### Créer la fiche de novembre
POST {{baseUrl}}/fiches
Authorization: Bearer {{jeton}}
Content-Type: application/json

{"mois": "2026-11"}

Que faut-il tester ?

Tester seulement le cas où tout va bien, c'est tester la moitié de l'API. Pour chaque route, passe en revue ces familles de cas :

Automatiser : les tests d'intégration

Les tests manuels ne se rejouent pas tout seuls. Un test d'intégration d'API démarre l'application (souvent avec une base de test), lui envoie de vraies requêtes HTTP et vérifie les réponses ; il tourne à chaque modification, en local et dans l'intégration continue. En Node.js, la bibliothèque supertest envoie les requêtes directement à l'application Express, sans ouvrir de port :

import { describe, it, expect } from 'vitest';
import request from 'supertest';
import app from '../src/app.js';
import { jetonPour } from './outils.js';   // fabrique un jeton de test signé

describe('POST /v1/fiches/:id/frais-hors-forfait', () => {
  const frais = { date: '2026-10-14', libelle: 'Taxi gare', montant: 18.4 };

  it('crée le frais sur la fiche en cours du visiteur', async () => {
    const res = await request(app)
      .post('/v1/fiches/12/frais-hors-forfait')
      .set('Authorization', `Bearer ${jetonPour({ sub: '7', role: 'visiteur' })}`)
      .send(frais);
    expect(res.status).toBe(201);
    expect(res.headers.location).toMatch(/^\/v1\/frais-hors-forfait\/\d+$/);
  });

  it("refuse la fiche d'un autre visiteur sans rien créer", async () => {
    const res = await request(app)
      .post('/v1/fiches/12/frais-hors-forfait')
      .set('Authorization', `Bearer ${jetonPour({ sub: '9', role: 'visiteur' })}`)
      .send(frais);
    expect(res.status).toBe(404);
  });

  it('refuse un montant négatif avec une erreur RFC 9457', async () => {
    const res = await request(app)
      .post('/v1/fiches/12/frais-hors-forfait')
      .set('Authorization', `Bearer ${jetonPour({ sub: '7', role: 'visiteur' })}`)
      .send({ ...frais, montant: -5 });
    expect(res.status).toBe(422);
    expect(res.headers['content-type']).toMatch(/application\/problem\+json/);
    expect(res.body.erreurs[0].champ).toBe('montant');
  });
});

Le même principe existe partout : WebTestCase de Symfony ou les tests HTTP de Laravel en PHP, WebApplicationFactory en ASP.NET Core, le TestClient de FastAPI en Python. Les tests unitaires, les tests d'intégration et la démarche de test en général sont présentés dans le cours Tests.

Deux compléments utiles :

• les tests de contrat vérifient que les réponses respectent le document OpenAPI : des outils comme Schemathesis génèrent même des centaines de requêtes inattendues à partir du document et signalent les réponses 500 ou non conformes ;
• les tests de charge mesurent le comportement sous la pression (temps de réponse, erreurs) avec des outils comme k6 ou JMeter. Lance-les sur un environnement dédié, jamais sur la production d'un tiers.

Exercices

# 1
curl -i "https://api.gsb.example/v1/fiches?etat=VA&mois=2026-10" -H "Authorization: Bearer $JETON"

# 2
curl -i --json '{"date":"2026-10-21","libelle":"Parking gare","montant":12}' \
  "https://api.gsb.example/v1/fiches/12/frais-hors-forfait" -H "Authorization: Bearer $JETON"

# 3
curl -i -X PATCH --json '{"etat":"CL"}' "https://api.gsb.example/v1/fiches/12" \
  -H "Authorization: Bearer $JETON"

# 4
curl -s -o /dev/null -w "%{http_code}\n" -X DELETE \
  "https://api.gsb.example/v1/frais-hors-forfait/58" -H "Authorization: Bearer $JETON"

# 5 : on attend 401 et un en-tête WWW-Authenticate
curl -i "https://api.gsb.example/v1/fiches/12"

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/problem+json

{"type":"https://api.gsb.example/problemes/format","title":"Format non pris en charge","status":415,"detail":"Le corps doit être envoyé en application/json."}

it('refuse la fiche d\'un autre visiteur', async () => {
  const res = await request(app)
    .get('/v1/fiches/12')
    .set('Authorization', `Bearer ${jetonPour({ sub: '9', role: 'visiteur' })}`);
  expect(res.status).not.toBe(200);
});

it("refuse la fiche d'un autre visiteur", async () => {
  const proprietaire = await request(app)
    .get('/v1/fiches/12')
    .set('Authorization', `Bearer ${jetonPour({ sub: '7', role: 'visiteur' })}`);
  expect(proprietaire.status).toBe(200);   // la fiche existe et le jeton de test fonctionne

  const autre = await request(app)
    .get('/v1/fiches/12')
    .set('Authorization', `Bearer ${jetonPour({ sub: '9', role: 'visiteur' })}`);
  expect(autre.status).toBe(404);
});