Concevoir des APIs HTTP dans Rails que votre équipe frontend appréciera vraiment

La plupart des plaintes des équipes frontend sur les APIs ne portent pas sur des fonctionnalités manquantes, mais sur l'incohérence : un endpoint renvoie les dates en chaînes ISO, un autre en timestamps Unix, et les erreurs reviennent sous trois formes différentes selon le contrôleur qui les a levées. La cohérence est le véritable livrable de la conception d'API.

Choisir une forme d'erreur une fois, l'appliquer partout

Un format d'erreur unique et prévisible permet au frontend d'écrire un seul gestionnaire d'erreurs au lieu d'un par endpoint.

rescue_from ActiveRecord::RecordInvalid do |e|
  render json: {
    error: { code: "validation_failed", message: e.message, fields: e.record.errors.as_json }
  }, status: :unprocessable_entity
end

Sérialiser explicitement, ne pas exposer le modèle

Rendre directement un objet ActiveRecord expose chaque colonne, y compris celles ajoutées le trimestre prochain pour une raison sans rapport. Un serializer dédié fait de la forme de la réponse un contrat délibéré plutôt qu'un accident du schéma.

Versionner dès le premier jour, même pour l'API interne d'un monolithe

Ajouter un préfixe de version aux routes ne coûte rien quand il n'y a qu'un seul consommateur. L'ajouter après coup, alors que trois intégrations externes dépendent déjà du chemin non versionné, coûte un plan de migration et une fenêtre de dépréciation. Nous ajoutons le préfixe même sur des APIs dont nous sommes certains qu'elles n'auront jamais qu'un seul client, parce que cette certitude se révèle généralement fausse en moins d'un an.

La pagination et le filtrage font partie du contrat, ils ne sont pas un détail

Un endpoint qui renvoie tous les enregistrements « pour l'instant » devient un incident de production le jour où cette table dépasse quelques centaines de milliers de lignes. Une pagination par curseur, documentée dès la première version, évite à la fois la chute de performance et le breaking change que représente l'ajout tardif d'une pagination à un client qui supposait un tableau simple.

Rien de tout cela ne consiste à suivre une spécification pour elle-même. Il s'agit de faire de l'API quelque chose sur lequel une équipe frontend peut construire sans avoir à lire le code source Rails pour deviner ce qui se passera ensuite.