REST (representational state transfer)

REST, pour representational state transfer, est un ensemble de règles de conception pour les API web. Une API REST traite tout comme une ressource dotée de sa propre adresse web, par exemple une commande, un produit ou un client, et utilise les verbes standard du web pour la lire ou la modifier.

Quand un développeur vous dit « la plateforme a une API REST », il veut dire que d'autres logiciels peuvent lui parler de cette façon familière et prévisible. Si vous faites appel à des freelances, comparez des outils ou lisez des pages d'intégration, vous croiserez ce mot sans arrêt. Vous n'avez pas à en construire une. Comprendre le principe vous aide à lire un devis, repérer les limites et poser de meilleures questions.

Qu'est-ce que REST ?

REST est un style d'architecture décrit en 2000 par l'informaticien Roy Fielding. Ce n'est ni un produit, ni une bibliothèque, ni un format de fichier. C'est une façon d'organiser une API autour des mêmes principes qui font fonctionner le web.

Les idées de base sont simples :

• Ressources : chaque objet métier est une ressource. Commandes, produits, clients et codes promo sont des ressources.
• Adresses : chaque ressource a une URL. La liste des commandes peut se trouver à /orders, et la commande 1042 à /orders/1042.
• Méthodes standard : on agit sur les ressources avec les verbes HTTP. GET lit, POST crée, PUT ou PATCH modifie, DELETE supprime.
• Représentations : le serveur renvoie une représentation de la ressource, presque toujours en JSON.
• Absence d'état (stateless) : chaque requête contient tout ce dont le serveur a besoin, y compris la preuve d'identité. Le serveur ne se souvient pas des appels précédents.
• Codes de statut : la réponse indique comment cela s'est passé. 200 veut dire que tout va bien, 201 créé, 404 introuvable, 401 non autorisé, 429 trop de requêtes, 500 erreur serveur.

REST n'est pas une norme stricte avec une certification. Beaucoup d'API dites REST prennent des libertés avec les règles. Dans la pratique, « API REST » désigne simplement une API web organisée autour de ressources, d'URL et de méthodes HTTP, qui renvoie du JSON.

REST n'est pas non plus la seule option. GraphQL permet au client de demander exactement les champs qu'il veut via une adresse unique. Les anciennes API SOAP utilisent du XML et des règles plus lourdes. Les webhooks, qui vous poussent des événements, accompagnent souvent une API REST sans la remplacer.

Pourquoi c'est important

REST est la langue par défaut des intégrations web. Presque tous les prestataires de paiement, outils d'emailing, services d'expédition et logiciels comptables proposent une API REST. Cela a des conséquences concrètes pour vous.

D'abord, le coût. REST étant partout, la plupart des développeurs freelances le connaissent déjà. Une marque qui veut envoyer les commandes de sa boutique vers son entrepôt trouve vite quelqu'un pour relier deux API REST. Une synchronisation simple des commandes payées dans un sens peut demander 3 jours à 500 € par jour, soit 1 500 €. Si l'un des deux côtés utilisait un protocole exotique, le même travail pourrait prendre deux fois plus longtemps.

Ensuite, la prévisibilité. Les API REST de sociétés différentes se ressemblent : un développeur peut estimer le travail en lisant la documentation avant de chiffrer. Vous pouvez lui demander de confirmer, endpoint par endpoint, que ce dont vous avez besoin existe.

Enfin, des limites à connaître. Comme une API REST renvoie des blocs de données fixes, certaines tâches demandent beaucoup d'appels. Prenez une boutique à 800 commandes par mois qui veut un rapport quotidien avec le client et les produits de chaque commande. Si l'API renvoie les commandes sans le détail des produits, l'intégration peut devoir faire un appel pour la liste plus un appel par commande, soit environ 27 appels par jour et plus de 800 par mois. Aucun problème. Mais à 50 000 commandes, la même logique se heurte aux limites de débit, et le développeur doit regrouper les appels ou mettre en cache. Le savoir vous aide à lire un devis qui mentionne « pagination » ou « rate limiting » comme un vrai travail, pas du remplissage.

Comment ça marche

Voici ce qui se passe lors d'un échange REST typique, décrit sans code :

• Le client choisit la ressource et le verbe. Pour lire une commande, il envoie un GET sur /orders/1042. Pour créer un client, il envoie un POST sur /customers avec les informations du client.
• Il ajoute des en-têtes. Ils contiennent la clé d'API ou le jeton et précisent que les données sont en JSON.
• Le serveur authentifie et vérifie les droits. Une clé invalide renvoie 401. Une clé valide sans les bons droits renvoie 403.
• Le serveur valide les données. Un email manquant sur un nouveau client renvoie 400 ou 422 avec une explication.
• Le serveur exécute l'action et répond. Il renvoie un code de statut et un corps JSON, par exemple la commande avec ses lignes, ses totaux et son statut.
• Les listes arrivent par pages. Demander tous les produits en renvoie par exemple 50 à la fois, avec un lien ou un curseur vers la page suivante.
• Les évolutions sont versionnées. Beaucoup d'API indiquent une version dans l'URL ou un en-tête, comme v2, pour que les anciennes intégrations continuent de fonctionner.

La plupart des API REST sont décrites dans un fichier OpenAPI, que les développeurs utilisent pour lire la documentation, tester des appels et générer du code.

Repères et exemples

Quelques repères sur les API REST que vous croiserez en tant que vendeur :

• Taille des pages : 20 à 250 éléments par page, c'est courant. Importer 10 000 produits à 100 par page représente 100 appels.
• Limites de débit : souvent entre 2 et 100 requêtes par seconde et par compte, parfois comptées à la minute ou à la journée.
• Temps de réponse : 100 à 500 millisecondes pour une lecture simple, c'est sain.
• Versions : une API bien gérée maintient l'ancienne version 12 à 24 mois après l'annonce d'une nouvelle.

Exemples du quotidien :

• L'API REST d'un prestataire de paiement reçoit un POST pour créer un paiement et renvoie son statut.
• Un service d'expédition expose /shipments pour créer des étiquettes et /tracking pour lire le statut des colis.
• Un outil d'emailing propose /contacts pour qu'une boutique ajoute chaque nouvel acheteur à une liste.
• Un logiciel comptable lit /invoices pour rapprocher les ventes en fin de mois.

Erreurs fréquentes

• Croire que toute « API REST » est complète. Certaines exposent les commandes mais pas les remboursements, ou les produits mais pas le stock. Vérifiez précisément les ressources et les méthodes.
• Interroger trop souvent. Demander les nouvelles commandes toutes les 5 secondes gaspille des requêtes et fait atteindre les limites. Un webhook qui pousse les nouvelles commandes est en général plus adapté.
• Ignorer la pagination. Une intégration qui ne lit que la première page rate en silence toutes les commandes après la cinquantième.
• Ne pas gérer les erreurs. Un 429 ou un 500 doit déclencher une nouvelle tentative après une pause, pas une commande perdue.
• Figer une ancienne version. Le jour où le fournisseur la retire, l'intégration s'arrête sans prévenir.

Bonnes pratiques

• Lisez la liste des ressources avant de vous engager. Faites une courte liste de vos besoins (commandes, stock, remboursements, clients) et cochez chacun dans la documentation.
• Demandez les limites dès le départ. Taille des pages, requêtes par seconde et quotas quotidiens disent si synchroniser tout votre catalogue est réaliste.
• Associez REST et événements. Utilisez REST pour lire et écrire, et les webhooks pour être prévenu des changements en temps réel.
• Donnez à chaque intégration ses propres identifiants. L'accès se révoque facilement et les problèmes se tracent vite.
• Journalisez chaque appel en échec. Un simple journal avec l'heure, l'endpoint et le code de statut transforme un bug mystérieux en correction de 10 minutes.
• Suivez les annonces de dépréciation. Abonnez-vous au journal des changements du fournisseur pour ne jamais être surpris par un changement de version.

Dans Roctify

Roctify est un SaaS : les ressources qu'une API REST exposerait entre outils séparés, comme les produits, les variantes, le stock, les clients et les commandes, partagent déjà un catalogue unique dans la plateforme. Votre page lien en bio, votre boutique en ligne et votre checkout lisent et écrivent les mêmes données, et Roctify connecte Stripe et PayPal pour les paiements sans que vous touchiez à une API.

Roctify ne propose pas d'API REST publique aujourd'hui. Quand vous avez besoin de vos données ailleurs, le plan Pro inclut rapports et exports. Si votre activité a besoin d'une connexion directe avec un autre système, les intégrations sur mesure se discutent dans le cadre du plan Enterprise.

FAQ

REST et API, c'est la même chose ?

Non. Une API est n'importe quelle interface qui permet à des programmes de communiquer. REST est un style de construction d'API web, le plus courant. Dire « API REST » vous indique comment l'API est organisée.

REST est-il meilleur que GraphQL ?

Aucun des deux n'est meilleur dans l'absolu. REST est plus simple, très connu et facile à mettre en cache, ce qui convient à la plupart des intégrations. GraphQL brille quand une application a besoin de données souples et imbriquées en une seule requête. Beaucoup de plateformes proposent l'un, l'autre ou les deux.

Une API REST est-elle sécurisée ?

REST ne dit rien de la sécurité en soi. Une API REST est sûre quand elle utilise HTTPS, une authentification solide, des droits limités et des limites de débit. Votre rôle consiste à protéger les clés que vous créez et à révoquer celles qui ne servent plus.