Qu'est-ce qu'une API REST ?

Une API REST est une API qui suit le style architectural REST : ressources à des URL, requêtes sans état et méthodes HTTP standard. REST — Representational State Transfer, défini dans la thèse de doctorat de Roy Fielding en 2000 — est un style, pas un protocole ni un standard : un ensemble de contraintes qui, honorées ensemble, produisent des API que tout le web sait déjà consommer, mettre en cache et mettre à l’échelle.

Points clés

Un cycle CRUD complet en HTTP brut

Tout le style en quatre requêtes — voilà ce que chaque framework et SDK finit par envoyer :

POST /v1/posts                     →  201 Created            créer
{ "title": "Hello REST" }             Location: /v1/posts/8fk2

GET /v1/posts/8fk2                 →  200 OK                 lire
                                      { "title": "Hello REST", … }

PUT /v1/posts/8fk2                 →  200 OK                 remplacer
{ "title": "Hello again" }            (PATCH mettrait à jour des champs)

DELETE /v1/posts/8fk2              →  204 No Content         supprimer
GET /v1/posts/8fk2                 →  404 Not Found          …et il a disparu

Le même cycle à travers les SDK qui enveloppent les appels REST :

// JavaScript / Node.js — Back4app JS SDK
// The REST semantics, wrapped: create, read, update, delete
const post = new Parse.Object('Post');
post.set('title', 'Hello REST');
await post.save();                            // POST   /classes/Post      → 201

const fetched = await new Parse.Query('Post')
  .get(post.id);                              // GET    /classes/Post/:id  → 200

fetched.set('title', 'Hello again');
await fetched.save();                         // PUT    /classes/Post/:id  → 200

await fetched.destroy();                      // DELETE /classes/Post/:id  → 200

// Flutter / Dart — Back4app Flutter SDK
// The REST semantics, wrapped: create, read, update, delete
final post = ParseObject('Post')..set('title', 'Hello REST');
await post.save();          // POST   /classes/Post      → 201

await post.fetch();         // GET    /classes/Post/:id  → 200

post.set('title', 'Hello again');
await post.save();          // PUT    /classes/Post/:id  → 200

await post.delete();        // DELETE /classes/Post/:id  → 200

// iOS / Swift — Back4app Swift SDK
// The REST semantics, wrapped: create, read, update, delete
var post = Post()
post.title = "Hello REST"
let saved = try await post.save()      // POST   /classes/Post      → 201

let fetched = try await saved.fetch()  // GET    /classes/Post/:id  → 200

var updated = fetched
updated.title = "Hello again"
_ = try await updated.save()           // PUT    /classes/Post/:id  → 200

try await updated.delete()             // DELETE /classes/Post/:id  → 200

// Android / Kotlin — Back4app Android SDK
// The REST semantics, wrapped: create, read, update, delete
val post = ParseObject("Post")
post.put("title", "Hello REST")
post.save()                                    // POST   /classes/Post      → 201

val fetched = ParseQuery.getQuery<ParseObject>("Post")
    .get(post.objectId)                        // GET    /classes/Post/:id  → 200

fetched.put("title", "Hello again")
fetched.save()                                 // PUT    /classes/Post/:id  → 200

fetched.delete()                               // DELETE /classes/Post/:id  → 200

Les six contraintes de REST

1. Client-serveur — interface et implémentation évoluent indépendamment ; l’UI ne sait jamais comment fonctionne le stockage.
2. Sans état — chaque requête est autonome ; le serveur ne garde aucune session entre les appels, ce qui permet à n’importe quelle réplique de répondre à n’importe quelle requête.
3. Cacheable — les réponses déclarent leur propre cacheabilité ; des GET avec de bons headers de cache mettent toute l’infrastructure de cache du web (navigateurs, CDN, proxys) au travail pour votre API.
4. Interface uniforme — la contrainte qui est REST, en quatre parties : ressources identifiées par des URI ; manipulation via des représentations (vous renvoyez le JSON que la ressource doit devenir) ; messages autodescriptifs (méthode + headers disent tout ce qu’il faut pour traiter la requête) ; et hypermédia comme moteur de l’état de l’application (les réponses lient les actions suivantes).
5. Système en couches — les clients ne peuvent pas savoir s’ils parlent à l’origine, à un cache ou à une gateway ; les intermédiaires s’insèrent librement.
6. Code à la demande (optionnel) — les serveurs peuvent envoyer du code exécutable aux clients ; la seule contrainte marquée optionnelle, et celle que la plupart des API ignorent.

Méthodes HTTP : sûreté, idempotence, CRUD

Le tableau qui manque à presque toutes les pages bien classées — la sémantique du RFC 9110, condensée :

Sûre signifie que la requête ne change rien ; idempotente, que la répéter ne change rien de plus. Ce n’est pas de la culture générale — c’est la politique de retry : un timeout réseau sur un PUT se réessaie sans crainte, le même timeout sur un POST exige une clé d’idempotence ou un contrôle de doublons. Le mapping CRUD complet a sa propre entrée.

Codes de statut : quoi renvoyer, et quand

Les distinctions 401/403 et 200/201/204 sont là où l’artisanat d’une API se voit : des codes précis rendent les clients débogables avec rien d’autre que la ligne de statut.

Votre API est-elle vraiment REST ? L’échelle de maturité

La section honnête que les explications commerciales omettent. Le Richardson Maturity Model note les API HTTP : niveau 0 (une URL, un verbe, du RPC déguisé), niveau 1 (des ressources à des URL), niveau 2 (méthodes et codes de statut corrects), niveau 3 (hypermédia — HATEOAS).

Sur l’insistance de Fielding lui-même, une API sans hypermédia n’est pas REST — il a écrit un essai acéré disant exactement cela. En pratique, presque chaque « API REST » acclamée est une API HTTP de niveau 2 : ressources, verbes, codes de statut, JSON, pas d’hypermédia. Cela compte moins comme pureté que comme vocabulaire — connaître l’échelle vous dit ce que le terme signifie dans une offre d’emploi (niveau 2) versus dans la thèse (niveau 3), et vous épargne à la fois le HATEOAS de cargo cult et les corrections pédantes.

REST vs. SOAP vs. GraphQL vs. gRPC

La comparaison avec GraphQL a droit à une entrée complète.

Les conventions qui rendent une API REST agréable

Au-delà des contraintes, les conventions sur lesquelles les consommateurs vous notent en silence : des ressources au pluriel (/posts, pas /getPost) ; une imbrication d’un niveau maximum (/posts/8fk2/comments, puis stop) ; la pagination sur chaque collection — par curseur pour la profondeur et la stabilité, avec des limites appliquées ; le filtrage et le tri en paramètres de requête, pas en variantes d’endpoint ; le versionnage avec une politique explicite (chemin /v1/ ou header — choisissez-en un, publiez des fenêtres de dépréciation) ; la négociation de contenu respectée (Accept, Content-Type) ; et des erreurs en JSON structuré avec un code lisible par les machines, pas seulement de la prose. Rien de tout cela n’est dans la thèse ; tout est dans la différence entre une API que les développeurs recommandent et une qu’ils subissent.

Cas d’usage courants

• API publiques et partenaires — l’ubiquité de REST est la fonctionnalité : chaque langage, outil et développeur le parle.
• Backends d’apps mobiles et web — le CRUD de ressources sur HTTP correspond à la façon dont la plupart des écrans consomment réellement les données.
• Frontières entre microservices — des contrats internes où l’outillage HTTP (gateways, tracing, cache) gagne sa place.
• Intégrations façon webhook — des systèmes qui notifient des systèmes par de simples appels HTTP que les deux côtés comprennent déjà.
• API de données générées automatiquement — les plateformes qui exposent une base de données comme ressources REST — le chemin le plus rapide du schéma à une API qui fonctionne.

Devriez-vous utiliser REST ? Matrice de décision

Limites et trade-offs

• Les représentations fixes ne vont pas à des clients divers. Le duo overfetching/underfetching est la faiblesse structurelle de REST ; les sparse fieldsets et les paramètres d’expansion atténuent, GraphQL redessine.
• Aucun contrat obligatoire. Rien n’impose une spec OpenAPI, donc beaucoup d’API REST sont documentées par folklore ; la discipline est optionnelle là où gRPC et GraphQL la rendent structurelle.
• L’absence d’état répète le contexte. L’auth et le contexte de tenant voyagent dans chaque requête — bon marché en octets, mais cela pousse la sémantique de session vers les tokens et rend certains flux (transactions en plusieurs étapes) inconfortables.
• La tentation du N+1 par design. Penser ressource-par-URL invite aux clients à un-appel-par-élément ; les bonnes API livrent expansion et batch avant que les consommateurs n’improvisent des boucles.
• Le mot « REST » est ambigu. API HTTP de niveau 2 dans la plupart des bouches, architecture hypermédia dans la thèse — lisez laquelle des deux une spec, une offre d’emploi ou un relecteur veut dire avant de débattre.

Les API REST sur Back4app

Back4app est une plateforme open-source de Backend as a Service (BaaS) qui combine une base de données gérée, des API REST et GraphQL générées automatiquement, l’authentification, le stockage de fichiers et des fonctions serverless avec Cloud Code. L’API REST ici est générée, pas construite : chaque classe de votre modèle de données est immédiatement une ressource — POST /classes/Post crée, GET /classes/Post/:id lit, avec les méthodes, les codes de statut et la sémantique de Location du parcours ci-dessus — derrière des clés, des tokens d’utilisateur et des permissions au niveau des classes qui font respecter la frontière. Les onglets de code montrent le même cycle à travers les SDK, qui sont de minces enveloppes idiomatiques sur exactement ce HTTP ; quand une opération dépasse le CRUD, une fonction Cloud Code ajoute un endpoint sur mesure dans un fichier. Du REST de niveau 2, correct par défaut, du schéma à l’URL le temps de définir la classe.