API — qu'est-ce que c'est ? API REST, webhook et OpenAPI expliqués pour l'entreprise

« On a une API pour ça » — c'est une phrase qu'entend tôt ou tard toute personne qui parle à des développeurs ou à un éditeur de logiciel. Une API, qu'est-ce que c'est ? En bref, la définition : une API (application programming interface, interface de programmation d'application) est une façon convenue pour qu'un programme demande à un autre des données ou l'exécution d'une action — sans intervention humaine, sans clics dans des écrans, et sans recopier des données d'une fenêtre à une autre.

Cet article s'adresse aux dirigeants et responsables d'entreprise qui veulent comprendre de quoi parlent leurs développeurs, suffisamment pour poser les bonnes questions. Nous commençons par des exemples concrets, puis passons aux notions qui reviennent dans toute conversation sur l'intégration : API REST, webhook, OpenAPI, clé API. Chaque définition est accompagnée d'un lien vers la source qui l'établit — documentation, spécification ou norme.

API — définition et exemples concrets

Le plus simple pour comprendre une API, c'est à travers trois services qu'utilisent beaucoup d'entreprises suisses, souvent sans savoir que cela passe par une API.

Un taux de change de référence auprès de la Banque nationale suisse. Un système financier qui saisit automatiquement un taux EUR/CHF dans une facture n'ouvre pas le site web de la BNS. Il envoie une requête au portail de données de la BNS, qui publie des moyennes mensuelles et des taux de fin de mois, entre autres séries statistiques, via un service web public.

Vérifier le numéro IDE d'une entreprise. Avant de référencer un nouveau fournisseur ou client, une entreprise peut vérifier automatiquement que la société est bien enregistrée sous le numéro d'identification des entreprises (IDE) qu'elle a indiqué. L'Office fédéral de la statistique propose pour cela les services publics du registre IDE — un service web avec des opérations telles que GetByUID, Search, ValidateUID et ValidateVatNumber. Contrairement aux autres exemples ici, c'est un service SOAP, pas REST — un bon exemple concret pour la section SOAP plus bas.

Rechercher une entreprise enregistrée. L'API Zefix PublicREST, l'index central suisse des raisons de commerce, publie une spécification OpenAPI 3.1.0 et exige des identifiants HTTP Basic pour être appelée — un bon exemple concret pour les sections OpenAPI et clé API plus loin.

Dans les trois cas, le schéma est le même : un programme (le client) envoie une requête dans un format convenu, et un autre (le serveur) renvoie une réponse, également dans un format convenu. Cet accord — quelles requêtes on peut envoyer, quelles données elles nécessitent, et ce qui revient en réponse — c'est exactement ce qu'est une API.

Voici à quoi cela ressemble en pratique. Ci-dessous, une requête pour le taux de change moyen mensuel EUR/CHF, effectuée le 2 octobre 2026 auprès du portail de données de la BNS, et la réponse du serveur :

1GET https://data.snb.ch/api/cube/devkum/data/json/en?dimSel=D0(M0),D1(EUR1)&fromDate=2026-09
Copy

1{"timeseries":[{"header":[{"dim":"Monthly average/End of month","dimItem":"Monthly average"},{"dim":"Currency","dimItem":"Europe - EUR 1"}],"metadata":{"key":"[email protected]{M0,EUR1}","frequency":"P1M","scale":"","unit":"Rates at 11 am. in CHF"},"values":[{"date":"2026-09","value":0.94312}]}]}
Copy

Pas besoin de savoir programmer pour lire ceci : 1 euro vaut 0,94312 franc suisse, en moyenne mensuelle pour septembre 2026. Un système financier fait exactement la même chose, en insérant simplement le chiffre dans le bon champ. (La requête ci-dessus a fonctionné sans inscription ni clé ; vérifiez les conditions d'utilisation de la BNS avant de bâtir dessus.)

API REST — ce que c'est et d'où ça vient

Quand un développeur dit « on a une API REST », il veut dire une API construite selon un style architectural particulier. Le terme REST (Representational State Transfer) a été introduit par Roy Fielding dans sa thèse de doctorat de 2000. Au chapitre 5, il le construit étape par étape, en ajoutant des contraintes à un système qui, au départ, n'en a aucune.

Les six contraintes REST selon Fielding

1. Client-serveur. Le client (l'application qui demande des données) et le serveur (le système qui les stocke) sont séparés et peuvent évoluer indépendamment.
2. Absence d'état (statelessness). Fielding écrit : « each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server » — traduction libre : chaque requête du client vers le serveur doit contenir toutes les informations nécessaires pour la comprendre, et ne peut pas s'appuyer sur un contexte stocké côté serveur. C'est pourquoi chaque requête vers une API transmet par exemple une clé — le serveur ne « se souvient » pas de qui a demandé une minute plus tôt.
3. Mise en cache. Les réponses peuvent être marquées comme pouvant être stockées et réutilisées, ce qui économise des requêtes futures.
4. Interface uniforme. C'est le cœur de REST. Fielding : « REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state » — traduction libre : REST est défini par quatre contraintes d'interface : l'identification des ressources, la manipulation des ressources via leurs représentations, des messages auto-descriptifs, et l'hypermédia comme moteur de l'état de l'application. En pratique : chaque ressource (une facture, un envoi, un lien) a sa propre adresse, et les opérations sur elle utilisent les mêmes méthodes standards.
5. Système en couches. Des intermédiaires — serveurs de cache, couches de sécurité — peuvent se trouver entre le client et le serveur sans que le client ait besoin de le savoir.
6. Code à la demande. Le serveur peut envoyer au client du code à exécuter. C'est la seule contrainte optionnelle — Fielding note qu'elle réduit la visibilité du système, « and thus is only an optional constraint within REST » — traduction libre : et n'est donc qu'une contrainte optionnelle au sein de REST.

API RESTful — ce que ça signifie

« API RESTful » signifie simplement une API qui suit ces règles. Dans l'usage courant, API REST et API RESTful désignent la même chose : une API accessible via HTTP, où les ressources ont des adresses et les opérations utilisent les méthodes HTTP standards. Beaucoup d'API dites REST ne respectent pas les six contraintes à la lettre — en particulier celle sur l'hypermédia. Pour une entreprise qui les utilise, cela n'a généralement pas d'importance : ce qui compte, c'est que l'API soit bien documentée et prévisible.

Méthodes HTTP et idempotence

Dans une API REST, c'est la méthode HTTP qui indique au serveur quoi faire avec une ressource. La sémantique des méthodes est fixée par la norme HTTP, aujourd'hui la RFC 9110 :

• GET — récupérer : « requests transfer of a current selected representation for the target resource » — traduction libre : demande le transfert d'une représentation actuelle de la ressource cible ;
• POST — traiter les données envoyées selon la sémantique propre de la ressource ; en pratique, le plus souvent : créer un nouvel enregistrement ;
• PUT — créer ou remplacer une ressource avec l'état envoyé dans la requête ;
• DELETE — supprimer l'association entre une ressource et sa fonction antérieure — en pratique : supprimer.

Pour une entreprise, la notion la plus importante de cette norme est l'idempotence. La RFC 9110 la définit ainsi : une méthode est idempotente « if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request » — traduction libre : si l'effet voulu, côté serveur, de plusieurs requêtes identiques avec cette méthode est le même que l'effet d'une seule requête de ce type. GET, PUT, DELETE et les autres méthodes sûres (lecture seule) sont idempotentes. POST ne l'est pas.

Pourquoi est-ce important ? Parce que les connexions se coupent. La norme explique qu'une requête idempotente peut être automatiquement renvoyée en toute sécurité si la communication s'interrompt avant que le client ne lise la réponse. Envoyer deux fois « supprimer la facture n° 15 » donne le même résultat qu'une seule fois. Envoyer deux fois « créer un paiement » peut créer deux paiements. C'est pourquoi les intégrations de paiement nécessitent une protection explicite contre les doublons — notre propre calculateur de coût d'application web le dit exactement à propos de ce poste : l'intégration des paiements « nécessite la gestion des webhooks, la logique d'idempotence et les tests de conformité — pas seulement l'intégration d'un widget de paiement ».

SOAP contre REST

Les systèmes plus anciens — bancaires, administratifs, d'entreprise — exposent souvent une API selon une autre norme : SOAP. Selon la spécification SOAP 1.2 du W3C (une recommandation depuis le 27 avril 2007), il s'agit d'un protocole décrit comme « a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment » — traduction libre : « un protocole léger destiné à l'échange d'informations structurées dans un environnement décentralisé et distribué », construit sur les technologies XML. Le registre IDE suisse lui-même, décrit plus haut, en est un exemple concret et actuel : c'est un service SOAP avec des opérations comme GetByUID et ValidateVatNumber, pas une API REST.

La différence pratique, du point de vue d'une entreprise, n'est pas idéologique. SOAP est un protocole avec sa propre enveloppe de message XML, strictement définie. REST est un style architectural qui utilise ce que HTTP offre déjà — adresses, méthodes et codes de statut — en transportant généralement les données en JSON. Si un fournisseur n'offre que SOAP, l'intégration reste tout à fait possible — elle nécessite simplement d'autres outils et généralement plus de travail pour traiter les messages. Nous ne citerons pas de statistiques sur la norme « la plus populaire », car nous n'en avons trouvé aucune que nous soyons prêts à garantir.

Webhook — ce que c'est et en quoi ça diffère d'un appel d'API

Une API classique fonctionne selon le principe « demande, et tu recevras une réponse ». Si vous voulez savoir si un client a payé, vous devez continuer à demander. Un webhook inverse ce sens : le système où quelque chose s'est produit envoie lui-même un message à une adresse que vous lui avez indiquée.

GitHub l'explique de la façon la plus simple possible dans sa documentation sur les webhooks : « Les webhooks vous permettent de recevoir des données telles qu'elles se produisent, plutôt que d'interroger une API (appeler une API par intermittence) pour vérifier si les données sont disponibles. » Stripe, l'opérateur de paiement, écrit qu'une fois un point de terminaison enregistré, « Stripe envoie des données en temps réel à celui-ci lorsque des événements se produisent sur votre compte Stripe », sous forme de JSON via HTTPS.

En pratique, les deux approches se complètent. Un webhook est préférable quand le temps de réponse compte — un paiement, une nouvelle commande, un changement de statut d'envoi. L'interrogation périodique suffit quand les données changent rarement, ou quand un fournisseur n'offre simplement pas de webhooks. Stripe donne un conseil important aux destinataires : « Renvoyer rapidement une réponse 2xx » — un point de terminaison qui reçoit des webhooks devrait répondre rapidement par un code de succès avant d'exécuter une logique complexe qui pourrait provoquer un délai d'attente dépassé.

Vérifier la signature d'un webhook

L'adresse qui reçoit les webhooks est publique — n'importe qui peut lui envoyer n'importe quoi, y compris un faux message « commande payée ». C'est pourquoi les fournisseurs sérieux signent chaque message, et le destinataire doit vérifier cette signature.

• Stripe place la signature dans l'en-tête Stripe-Signature, générée comme un HMAC avec SHA-256, en utilisant un secret propre à ce point de terminaison. Un horodatage est signé avec le corps du message. L'horodatage protège contre la rediffusion d'un ancien message intercepté : « Nos bibliothèques ont une tolérance par défaut de 5 minutes entre l'horodatage et l'heure actuelle » (Stripe, webhooks).
• GitHub envoie sa signature dans l'en-tête X-Hub-Signature-256, toujours précédée du préfixe sha256=. La documentation déconseille de comparer les signatures avec un simple opérateur ==, et recommande une « comparaison de chaînes en temps constant » plutôt — une comparaison qui ne peut pas être devinée en chronométrant la réponse (GitHub, validation des livraisons de webhooks).

HMAC est une signature créée avec un secret partagé : seuls l'expéditeur et le destinataire le connaissent, donc seuls eux peuvent générer et vérifier une signature correcte. Pour un dirigeant d'entreprise, la conclusion est simple : en interrogeant un fournisseur d'intégration sur les webhooks, demandez aussi si les messages sont signés, et si votre système vérifie cette signature.

OpenAPI — ce que c'est, et pourquoi une entreprise a besoin de documentation d'API

Une API sans documentation est comme un contrat que personne n'a mis par écrit. OpenAPI est la norme qui permet d'écrire ce contrat. La version actuelle de la spécification est OpenAPI Specification 3.2.1, publiée le 10 septembre 2026. Sa première phrase explique son objectif : « The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. » — traduction libre : la spécification OpenAPI définit une description d'interface standard, indépendante du langage de programmation, pour les API HTTP, qui permet aux humains comme aux ordinateurs de découvrir et de comprendre les capacités d'un service sans accéder au code source, à une documentation supplémentaire ni au trafic réseau.

En pratique, un fichier OpenAPI liste toutes les adresses de l'API, les méthodes, les champs requis, les réponses possibles et la méthode d'authentification. Des outils peuvent générer, à partir de ce fichier, une documentation lisible et navigable, permettant à un développeur d'envoyer immédiatement une requête de test. L'API Zefix PublicREST, mentionnée plus haut, en est un bon exemple local : sa spécification OpenAPI 3.1.0 publiée liste des points de terminaison tels que la recherche d'entreprises et les consultations par IDE, avec les identifiants HTTP Basic requis.

Pourquoi est-ce important pour une entreprise, pas seulement pour les développeurs ?

• Changer de prestataire ne repart pas de zéro. Si l'API de votre système est décrite en OpenAPI, une nouvelle équipe sait ce qu'elle fait sans lire tout le code.
• Les partenaires peuvent s'intégrer eux-mêmes. Plutôt que d'expliquer par e-mail à chaque partenaire comment envoyer une commande, vous lui donnez un lien vers la documentation.
• Il est plus facile de vérifier ce qui a été livré. La spécification est un livrable concret que vous pouvez réceptionner en même temps que l'application.

C'est pourquoi, dans notre propre calculateur, le poste « API publique / intégrations » est décrit, dans ses propres termes, comme incluant « les clés API, le rate limiting et la doc OpenAPI » — pas seulement le code sous-jacent.

Clés API et sécurité des intégrations

Clé API, jeton Bearer et limites de requêtes

Une clé API est une chaîne de caractères longue et aléatoire qui identifie le programme envoyant les requêtes et lui donne accès. Elle est le plus souvent transmise dans l'en-tête Authorization sous forme de jeton Bearer — « le porteur » : qui le détient a accès. Certains fournisseurs exigent plutôt des identifiants HTTP Basic, comme c'est le cas pour l'API Zefix PublicREST. Trois règles pratiques s'appliquent dans tous les cas. Les identifiants restent uniquement sur le serveur, jamais dans du code visible dans un navigateur ni dans un e-mail. Chaque intégration devrait avoir ses propres identifiants, afin qu'une fuite permette de révoquer un seul jeu plutôt que tous. Il vaut la peine de renouveler les identifiants périodiquement.

Certains fournisseurs utilisent la norme OAuth à la place, où une application obtient un jeton au nom d'un compte spécifique.

Le second élément est la limitation de débit (rate limiting). Un fournisseur limite le nombre de requêtes que l'on peut envoyer dans un temps donné, pour qu'un seul client ne surcharge pas le service. Une API bien conçue vous en informe dans ses réponses — par exemple via des en-têtes indiquant la limite, le nombre de requêtes restantes et le moment de réinitialisation. Votre intégration doit respecter ces limites : répartir les requêtes dans le temps, et ne pas réessayer en boucle après un refus.

Top 10 OWASP API Security 2023

L'OWASP, l'organisation spécialisée dans la sécurité des applications, publie son propre top dix des risques pour les API. L'édition 2023 se présente ainsi (titres tels que publiés, explications de notre fait) :

1. API1:2023 – Broken Object Level Authorization — l'API ne vérifie pas si le demandeur a le droit d'accéder à un enregistrement précis ; changer un numéro de facture dans l'adresse affiche la facture de quelqu'un d'autre.
2. API2:2023 – Broken Authentication — gestion défaillante de la connexion, des clés ou des jetons.
3. API3:2023 – Broken Object Property Level Authorization — absence de contrôle sur des champs individuels : l'API renvoie ou permet de modifier des champs auxquels un utilisateur ne devrait pas avoir accès.
4. API4:2023 – Unrestricted Resource Consumption — absence de limites sur les requêtes ou les ressources, avec risque de surcharge ou de factures incontrôlées.
5. API5:2023 – Broken Function Level Authorization — un utilisateur ordinaire peut appeler des fonctions destinées à un administrateur.
6. API6:2023 – Unrestricted Access to Sensitive Business Flows — des processus métier (achats, réservations, inscriptions) peuvent être automatisés massivement, au détriment de l'entreprise.
7. API7:2023 – Server Side Request Forgery — l'API récupère une ressource à une adresse fournie par l'utilisateur, et peut être amenée à requêter des endroits qu'elle ne devrait pas atteindre.
8. API8:2023 – Security Misconfiguration — erreurs de configuration : fonctionnalités inutiles activées, absence de mises à jour, messages d'erreur trop détaillés.
9. API9:2023 – Improper Inventory Management — une entreprise ne sait pas quelles versions et quels points de terminaison d'API elle a exposés ; de vieilles versions oubliées restent ouvertes.
10. API10:2023 – Unsafe Consumption of APIs — confiance excessive dans les données provenant des API d'autrui, sans les vérifier.

Ce dernier point concerne toute entreprise qui se contente d'utiliser les API d'autres acteurs : les données externes doivent aussi être vérifiées. Comment la responsabilité de la sécurité se répartit réellement lorsque les données se trouvent chez un prestataire externe est expliqué dans notre article sur la sécurité des données dans le cloud.

API publiques qu'une entreprise suisse rencontre réellement

Beaucoup d'intégrations dans les entreprises suisses touchent les mêmes quelques services publics. Voici une courte liste avec des liens vers la documentation officielle.

• API du portail de données de la BNS — publie les taux de change et d'autres séries statistiques de la Banque nationale suisse via un service web public (data.snb.ch).
• Registre IDE — services publics — un service web SOAP de l'Office fédéral de la statistique pour consulter et valider l'IDE d'une entreprise, avec notamment une opération de validation de numéro de TVA (uid-wse.admin.ch).
• API Zefix PublicREST — l'index central suisse des raisons de commerce, publié sous forme de spécification OpenAPI 3.1.0, exigeant des identifiants HTTP Basic pour être appelé (zefix.admin.ch).
• QR-facture — la norme suisse de données de facturation, portant toutes les informations nécessaires à un paiement sous forme numérique ; utile à connaître à côté de n'importe laquelle des API ci-dessus.

Un exemple de notre propre site : comment nous utilisons l'API DVN Links

L'exemple d'intégration le plus honnête que nous puissions montrer est le nôtre. DVN Links est notre propre produit — le site anglophone le décrit comme « a European link management platform with analytics and QR codes », traduction libre : une plateforme européenne de gestion de liens avec analytique et codes QR. Le site que vous lisez utilise son API REST publique à chaque publication d'un article ou d'une page — la même API que reçoivent les clients des plans payants (selon sa page de tarifs, l'accès à l'API commence au plan Starter).

Ce que fait concrètement notre site, en termes simples :

1. Crée un lien court à la publication. Si un document n'a pas encore de lien court, le site envoie une requête POST /links avec l'adresse cible et enregistre le lien court obtenu ainsi que son identifiant sur le document.
2. Vérifie le lien lors des publications suivantes. Si un identifiant existe déjà, le site demande via GET /links/{id} si le lien existe toujours et où il mène.
3. Recrée un lien si quelqu'un l'a supprimé dans le panneau DVN Links — il se contente d'en créer un nouveau.
4. Met à jour la cible en cas de changement d'adresse. Quand l'adresse d'un article change, le site envoie PATCH /links/{id} avec la nouvelle cible. L'ancien lien court continue de fonctionner et pointe désormais vers la nouvelle adresse.
5. Reprend les anciens liens. Les documents qui avaient un lien court enregistré avant cette intégration, mais sans identifiant, sont retrouvés par recherche de l'adresse cible exacte, et le lien trouvé est adopté plutôt que d'en créer un doublon.

Deux décisions de conception comptent ici plus que les requêtes elles-mêmes. D'abord, l'intégration ne bloque jamais la publication — si DVN Links ne répond pas, l'article est publié quand même, et l'erreur part seulement dans les journaux. Ensuite, sans clé API configurée, l'intégration ne fait simplement rien. On retrouve aussi en pratique le point sur l'idempotence vu plus haut : POST crée une nouvelle ressource, donc avant de l'appeler, le site vérifie toujours si un lien existe déjà.

L'API de DVN Links elle-même a des caractéristiques qu'il vaut la peine de demander à tout fournisseur. Elle est décrite par une spécification OpenAPI 3.1.0, à partir de laquelle est générée une documentation navigable. Chaque requête exige une clé transmise comme jeton Bearer dans l'en-tête Authorization. Les limites de débit dépendent du plan, et chaque réponse porte les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset.

DVN Links n'a pas de webhooks. C'est donc un exemple d'interrogation périodique : notre site vérifie lui-même l'état d'un lien, quand il en a besoin, plutôt que d'attendre une notification. Pour cet usage, cela suffit, car nous ne vérifions le lien qu'au moment de la publication.

Intégrer via une API plutôt que recopier les données — quand ça vaut le coup

Chaque intégration par API remplace un travail que quelqu'un dans l'entreprise effectue aujourd'hui à la main : recopier des commandes d'une plateforme vers un système d'entrepôt, coller un taux de change dans une facture, vérifier un partenaire commercial avant un virement. La question n'est pas « faut-il intégrer », mais « quelle recopie manuelle nous coûte vraiment le plus ».

Intégrer via une API a généralement du sens quand :

• la même action se répète souvent — quotidiennement, ou à chaque commande, pas une fois par trimestre ;
• une erreur coûte cher — un mauvais numéro de compte, un montant de facture erroné, un envoi qui ne part jamais ;
• le temps de réponse compte — un client attend la confirmation d'un paiement ou un numéro d'envoi ;
• les deux parties ont des API documentées — idéalement en OpenAPI, ou au moins avec une documentation complète et un environnement de test.

L'intégration n'a pas de sens quand l'action est rare, ou quand un fournisseur n'a pas d'API, ou la modifie sans préavis. Dans ce cas, maintenir l'intégration finit par coûter plus cher que le travail manuel.

Le coût d'une intégration dépend de son périmètre — nous chiffrons chaque intégration individuellement, car cela dépend fortement de la qualité de l'API en face. Notre calculateur de coût d'application web donne un point de départ approximatif pour les deux postes les plus courants : les intégrations d'API publiques, et l'intégration de paiements en ligne.

Quand plusieurs intégrations existent et commencent à former une chaîne — une commande, une facture, une étiquette d'envoi, une notification client — c'est déjà de l'automatisation de processus, pas une simple connexion. Nous en parlons dans notre article sur l'automatisation des processus métier, et notre approche est décrite sur notre page automatisation des processus. Si les intégrations doivent faire partie d'un nouveau système, commencez par notre article sur ce qu'est une application web et notre offre de développement d'applications web. Quand les outils prêts à l'emploi avec intégrations ne suffisent pas, il reste le logiciel sur mesure. Nous avons regroupé nos autres articles sur les applications web dans notre guide des applications web.