Les API REST expliquées aux non-développeurs

Qu’est-ce qu’une API REST ?

Lorsque vous utilisez une application, une grande partie des informations affichées à l’écran provient de services externes.

La météo de votre destination, le statut d’une livraison, le prix d’un produit, une réservation ou le résultat d’un paiement : bien souvent, l’application ne gère pas directement toutes ces données. Elle les demande à d’autres systèmes.

C’est là qu’interviennent les API. Une API permet à deux systèmes logiciels de communiquer selon des règles définies. Une API REST est l’un des moyens les plus courants d’établir cette communication sur le Web. Vous pouvez l’imaginer comme une conversation structurée entre applications :

« Donne-moi les informations sur ce produit. »

Le service répond :

« Voici son nom, son prix et sa disponibilité. »

Ou encore :

« Crée une nouvelle réservation pour ce client. »

Et le service peut répondre :

« Réservation créée. »

REST signifie Representational State Transfer. Il n’est pas nécessaire de retenir cet acronyme pour comprendre son fonctionnement. Le principe fondamental est plus simple : une API REST organise les données en ressources — comme des utilisateurs, des produits, des commandes ou des réservations — et définit une méthode standard pour les consulter, les créer, les modifier ou les supprimer.

Un exemple concret

Imaginez une application de voyage qui affiche la météo de la destination que vous allez visiter. L’application n’a pas besoin de collecter et de mettre à jour elle-même toutes les données météorologiques. Elle peut envoyer une requête à l’API d’un service météo.

Le flux est le suivant :

Votre application → requête API → service météo → réponse → votre application

La réponse peut contenir la température, les conditions météorologiques et les prévisions des prochains jours. L’utilisateur voit simplement la météo. Pourtant, derrière cet écran, deux systèmes communiquent entre eux.

L’analogie du restaurant

Une façon simple de comprendre une API consiste à imaginer que vous êtes au restaurant.

• Vous êtes l’application qui souhaite obtenir quelque chose.
• Le menu décrit ce que vous pouvez demander.
• Le serveur transmet la demande et rapporte la réponse.
• La cuisine est le service qui effectue le travail.

L’API joue à la fois le rôle du menu et du serveur. Elle indique ce que vous pouvez demander, comment formuler votre requête et quel type de réponse vous pouvez attendre. Vous n’avez pas besoin de savoir comment fonctionne la cuisine pour commander un plat. De la même manière, une application n’a pas nécessairement besoin de connaître le fonctionnement interne d’un service pour utiliser son API.

Comment fonctionne une requête API REST ?

Chaque requête API contient plusieurs informations essentielles.

Endpoint : où envoyer la requête

L’endpoint est l’adresse à laquelle la requête est envoyée. Par exemple :

https://api.example.com/products/42

Cette adresse peut représenter le produit dont l’identifiant est 42. Différents endpoints peuvent représenter un ensemble de ressources, un élément précis ou une opération particulière.

Méthode HTTP : ce que vous voulez faire

La méthode HTTP indique au service l’opération que vous souhaitez effectuer. Les méthodes les plus courantes sont :

• GET → récupérer des informations ;
• POST → créer une nouvelle ressource ;
• PUT ou PATCH → modifier une ressource existante ;
• DELETE → supprimer une ressource.

Par exemple, sur une plateforme de réservation :

GET /bookings

peut servir à récupérer les réservations, tandis que :

POST /bookings

peut permettre d’en créer une nouvelle. Ces conventions sont très répandues, mais elles ne constituent pas une garantie absolue. La documentation de l’API reste toujours la référence à suivre.

Headers et body : les informations complémentaires

Les headers contiennent des informations qui accompagnent la requête, comme le format des données ou les identifiants utilisés pour l’authentification. Le body, quant à lui, contient les données nécessaires à l’exécution de l’opération. Si vous souhaitez créer une réservation, par exemple, le body peut contenir :

{
  "service": "Consultation",
  "date": "2026-09-15",
  "time": "14:00"
}

Ces données sont souvent représentées en JSON, un format très répandu parce qu’il est structuré et facile à lire, aussi bien pour les humains que pour les logiciels.

Que se passe-t-il à la réception de la réponse ?

Après avoir reçu la requête, le service la traite et renvoie une réponse. Cette réponse contient généralement les données demandées ou le résultat de l’opération, ainsi qu’un code de statut HTTP qui indique ce qui s’est passé. Les codes les plus courants appartiennent à trois grandes catégories.

200–299 : tout s’est bien passé

La requête a été traitée correctement. Par exemple :

• 200 OK → requête terminée avec succès ;
• 201 Created → nouvelle ressource créée.

400–499 : la requête présente un problème

Le problème concerne généralement la requête ou les autorisations du client. Par exemple :

• 400 Bad Request → données non valides ;
• 401 Unauthorized → authentification absente ou non valide ;
• 403 Forbidden → l’utilisateur ne dispose pas des autorisations nécessaires ;
• 404 Not Found → la ressource demandée n’existe pas.

500–599 : problème côté serveur

Le service chargé de traiter la requête a rencontré un problème. Pour l’utilisateur, toutefois, un code comme 409 ou 500 ne signifie pas grand-chose. Une bonne application transforme donc l’erreur technique en un message compréhensible :

« Ce créneau n’est plus disponible. Choisissez un autre horaire. »

est bien plus utile que :

« HTTP 409 Conflict. »

API REST, base de données, webhook et GraphQL : quelles différences ?

Ces technologies et concepts sont liés, mais ils remplissent des rôles différents.

API REST et base de données

Une base de données sert à stocker des informations. Une API définit quant à elle la manière dont d’autres systèmes peuvent interagir avec ces informations. Par exemple, une base de données peut contenir :

• des utilisateurs ;
• des produits ;
• des commandes ;
• des réservations.

L’API peut déterminer quelles données peuvent être consultées, créées ou modifiées, et par qui. Elle crée ainsi une couche de contrôle entre l’application et les données. Connecter directement un navigateur à une base de données sans protections adaptées pourrait en effet exposer des informations ou des opérations qui devraient rester privées. Dans Coderblock, l’agent peut concevoir et appliquer le schéma d’une base de données Postgres à partir de la conversation. Les applications Web standard utilisent un projet Supabase dédié comprenant Postgres, Auth, Storage et Row Level Security. La section Backend permet également de consulter les tables, les utilisateurs authentifiés, le stockage et les fonctions.

API REST et webhook

Les API et les webhooks fonctionnent dans des directions différentes. Avec une requête API classique, c’est votre application qui demande une information :

« Le paiement a-t-il bien été effectué ? »

Avec un webhook, c’est au contraire un autre service qui informe spontanément votre application qu’un événement vient de se produire :

« Le paiement vient d’être effectué. »

Les webhooks sont particulièrement utiles pour les événements qui se produisent ultérieurement, comme les paiements, les mises à jour de livraison ou les changements de statut d’une commande. Ils doivent toutefois être vérifiés et traités de manière sécurisée. Dans le flux Stripe géré par Coderblock, la plateforme peut prendre en charge la configuration du webhook. En mode BYOK, l’agent demande la clé secrète Stripe de manière sécurisée et configure automatiquement le webhook.

REST et GraphQL

REST et GraphQL sont deux approches différentes de la communication entre applications. Avec REST, vous travaillez généralement avec plusieurs endpoints représentant différentes ressources. GraphQL utilise plutôt une interface de requête grâce à laquelle le client peut préciser les données qu’il souhaite recevoir. GraphQL peut être particulièrement utile lorsque les besoins en données sont complexes et que le client doit disposer d’un contrôle accru sur la réponse. REST, en revanche, est très répandu et souvent plus simple à comprendre. Il n’existe cependant pas d’approche universellement supérieure. Le choix dépend de l’architecture du service, des besoins du produit, de l’équipe et du type de client qui devra l’utiliser.

Authentification et autorisation : ce n’est pas la même chose

Deux concepts sont souvent confondus : l’authentification et l’autorisation. La différence est simple. Authentification :

« Qui êtes-vous ? »

Autorisation :

« Qu’avez-vous le droit de faire ? »

Imaginez une plateforme utilisée par des clients et des administrateurs. La connexion permet de vérifier que vous êtes bien l’utilisateur que vous prétendez être. Mais cela ne signifie pas automatiquement que vous pouvez consulter toutes les données de l’application. Un client peut voir ses propres réservations. Un administrateur peut voir celles de tous les clients. L’identité constitue la même information de base, mais les autorisations diffèrent.

Et les clés API ?

Une clé API identifie souvent l’application ou le service qui effectue une requête. Une session authentifiée peut, quant à elle, identifier l’utilisateur qui s’est connecté. Aucune des deux ne doit être considérée comme un laissez-passer universel.

Les autorisations doivent être définies séparément et appliquées également côté serveur ou dans la base de données. Dans Coderblock, vous pouvez demander directement dans le chat :

« Ajoute la connexion et les comptes utilisateurs. »

L’agent peut configurer Supabase Auth, les pages d’inscription et de connexion, la gestion des sessions, les routes protégées et la Row Level Security associée à l’utilisateur authentifié. Les applications comprennent également une structure de base pour les profils et les rôles. Il n’est donc pas nécessaire de créer manuellement une table pour les mots de passe ni de développer toute la logique d’authentification à partir de zéro.

Où stocker les clés API ?

Les identifiants privés constituent un autre point essentiel. Une clé API secrète ne doit pas être intégrée au front-end, publiée sur GitHub ou enregistrée dans un champ accessible aux utilisateurs. Lorsqu’un projet Coderblock nécessite un secret, l’agent peut le recueillir au moyen d’une demande sécurisée destinée aux variables d’environnement. La valeur est conservée dans le coffre de secrets côté serveur du projet et n’est ajoutée ni au code du front-end ni à la conversation.

Comment concevoir une fonctionnalité qui utilise une API

Lorsque vous créez une application avec un outil de développement par IA, vous n’avez pas besoin de commencer par la technologie. Partez du résultat que vous souhaitez obtenir pour l’utilisateur. « Montre aux clients le statut de livraison de leur commande » est une demande plus utile que :

« Ajoute une API. »

Vous pouvez ensuite définir ce dont vous avez besoin.

1. Identifiez la source des données

Quel système contient les bonnes informations ? Votre base de données ? Un service externe ? Stripe ? Un système de gestion des livraisons ? Vous devez disposer d’une source de vérité clairement définie.

2. Consultez la documentation

Avant d’intégrer un service, vérifiez :

• les endpoints disponibles ;
• le mode d’authentification ;
• les environnements de test ;
• les limites d’utilisation ;
• le format des requêtes et des réponses ;
• la prise en charge éventuelle des webhooks.

3. Anticipez les erreurs

Que se passe-t-il si le service externe est lent ? Et s’il est temporairement indisponible ? Et s’il renvoie des données incomplètes ? Une application bien conçue doit adopter un comportement défini même lorsqu’une API ne répond pas comme prévu.

4. Validez les données entrantes et sortantes

Ne partez pas du principe que les données provenant d’un service externe sont toujours correctes. Elles doivent être validées avant d’être utilisées ou enregistrées.

5. Limitez les autorisations

Une intégration ne doit disposer que des accès dont elle a réellement besoin. Si un service doit consulter les paiements, cela ne signifie pas nécessairement qu’il doit aussi pouvoir les modifier.

6. Protégez les secrets

Les identifiants privés doivent rester côté serveur. Le navigateur ne doit pas recevoir une clé API permettant d’effectuer des opérations sensibles.

7. Testez avant la mise en production

Lorsque cela est possible, utilisez l’environnement de test du service. Ne vérifiez pas uniquement les opérations réussies : testez également les requêtes refusées, les erreurs, les délais d’expiration, les doublons et les annulations.

8. Évitez les appels inutiles

Il n’est pas nécessaire de redemander toutes les informations à chaque chargement de page. Lorsque les données le permettent, la mise en cache peut réduire les temps de réponse, le nombre d’appels et les coûts de l’intégration.

Travailler avec des API dans Coderblock

Avec Coderblock, les API s’intègrent au même flux conversationnel que celui utilisé pour construire le reste de l’application. Vous pouvez partir d’une idée ou d’un modèle de produit et demander à l’IA de créer le front-end, le back-end et la base de données.

Lorsque vous souhaitez ajouter une intégration, il est utile de décrire le comportement attendu. Par exemple :

« Ajoute la connexion aux comptes. Chaque client doit pouvoir consulter uniquement ses propres réservations. Si le service externe de planification n’est pas disponible, affiche un message clair et permet à l’utilisateur de réessayer. »

Une demande de ce type précise non seulement la technologie à utiliser, mais surtout ce qui doit se passer dans l’application. L’agent peut se charger de l’implémentation sous-jacente, tandis que vous vérifiez le résultat dans l’aperçu en direct sur coderblock.dev et continuez à l’améliorer depuis le chat.

Pourquoi comprendre les API est utile même sans savoir programmer

Vous n’avez pas besoin d’être développeur pour comprendre le concept d’API REST. Mais en connaître les bases change votre manière de concevoir une application. Vous pouvez ainsi comprendre pourquoi une intégration avec Stripe diffère d’une connexion à une base de données, pourquoi un webhook n’est pas une requête API classique et pourquoi une clé API ne doit jamais être exposée dans le front-end. Surtout, cela vous aide à mieux formuler vos demandes à l’IA.

Au lieu de demander simplement :

« Ajoute une API. »

vous pouvez décrire ce qui doit se passer, quelles données doivent être utilisées, qui peut y accéder et comment l’application doit réagir en cas de problème. L’IA peut prendre en charge une grande partie de la complexité technique.

Mais plus vous décrivez clairement le comportement que vous souhaitez obtenir, plus vous gardez le contrôle sur le produit que vous construisez.