Bonnes pratiques d'API

Une API n'est pas seulement un ensemble de routes qui fonctionnent : c'est un contrat public que d'autres équipes vont consommer pendant des années. Ces pratiques évitent de casser leurs clients à chaque évolution.

🏷️ Versionner l'API

Dès qu'une modification casse la compatibilité (champ supprimé, format changé), il faut une nouvelle version.

GET /v1/articles      # version dans l'URL, la plus lisible
GET /articles         # + en-tête Accept: application/vnd.api.v2+json

Ce qui ne casse pas la compatibilité : ajouter un champ optionnel, ajouter une route. Ce qui la casse : renommer un champ, changer un type, rendre un paramètre obligatoire.

⚠️ Un format d'erreur uniforme

Tous les échecs doivent renvoyer la même structure, quelle que soit la route.

{
  "erreur": {
    "code": "VALIDATION_ECHOUEE",
    "message": "Le champ « email » est invalide.",
    "details": [{ "champ": "email", "raison": "format" }]
  }
}

// Middleware d'erreur Express (4 arguments)
app.use((err, req, res, next) => {
  const status = err.status ?? 500
  res.status(status).json({
    erreur: {
      code: err.code ?? "ERREUR_INTERNE",
      message: status === 500 ? "Erreur interne." : err.message,
    },
  })
})

🧭 HATEOAS en bref

HATEOAS consiste à joindre à chaque réponse les liens vers les actions possibles, pour que le client navigue sans coder les URLs en dur.

{
  "id": 42,
  "titre": "REST expliqué",
  "_links": {
    "self": { "href": "/v1/articles/42" },
    "commentaires": { "href": "/v1/articles/42/commentaires" }
  }
}

C'est le niveau le plus abouti du modèle de maturité de Richardson. Peu d'API l'appliquent intégralement, mais le principe reste utile pour la pagination (liens next et prev).

🌍 CORS

Un navigateur bloque par défaut les requêtes vers une autre origine. Le serveur doit explicitement autoriser les origines légitimes.

npm install cors

const cors = require("cors")

app.use(cors({
  origin: ["https://mon-front.fr"],
  methods: ["GET", "POST", "PATCH", "DELETE", "OPTIONS"],
  credentials: true,
}))

🛡️ Sécurité minimale

📖 Documenter avec OpenAPI

OpenAPI (ex-Swagger) décrit l'API dans un fichier YAML ou JSON exploitable par des outils de documentation et de génération de clients.

paths:
  /articles/{id}:
    get:
      summary: Récupérer un article
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200": { description: Article trouvé }
        "404": { description: Article inexistant }

➡️ Suite

La page Consommer et tester montre comment appeler et vérifier votre API.