Définition d'une APIguide d'introduction aux API pour débutants

Vous utilisez des API des dizaines de fois par jour sans le remarquer. Consulter la météo sur votre téléphone, envoyer un message, payer quelque chose en ligne : chacune de ces actions transmet discrètement une requête à une API et attend une réponse. Le mot ressemble à une infrastructure profonde, mais l'idée derrière est simple, et une fois que vous avez saisi le concept, vous voyez des API partout.

Ce guide vous donne une définition opérationnelle d'une API en langage courant et en termes techniques, puis explique comment les API font réellement circuler les données : requêtes et réponses, endpoints, méthodes, authentification, et le JSON qu'elles renvoient. Nous couvrons ensuite les principaux styles que vous rencontrerez (REST, SOAP, GraphQL et webhooks), examinons des exemples concrets, et montrons comment une API de scraping transforme un site web désorganisé qui n'a pas d'API officielle en quelque chose que vous pouvez appeler comme une API.

Définition d'une API : ce qu'est réellement une API

Une API, abréviation d'Application Programming Interface (interface de programmation d'application), est un ensemble de règles permettant à deux logiciels de communiquer entre eux. Un programme demande quelque chose ; l'autre programme répond dans un format prévisible. L'API est le contrat convenu au milieu qui définit comment poser la question et ce que vous recevrez en retour.

La façon classique de se la représenter est un restaurant. Vous êtes assis à une table (votre application), vous lisez un menu de ce que vous êtes autorisé à commander (les options documentées de l'API), et vous dites au serveur ce que vous voulez. Le serveur (l'API) porte votre commande à la cuisine (le serveur), attend qu'elle soit préparée, et vous apporte le résultat à votre table. Vous n'entrez jamais dans la cuisine, et vous n'avez pas besoin de savoir comment le plat est cuisiné. Il vous suffit de savoir ce qui est au menu et comment le commander.

En termes techniques, une API expose une interface définie aux données ou fonctions d'un système tout en cachant l'implémentation derrière elle. Elle fait abstraction de la base de données, de la logique métier et du code interne, et donne au monde extérieur un ensemble stable d'opérations à appeler. Cette abstraction est toute la valeur : la cuisine peut changer entièrement ses recettes, et tant que le menu reste le même, votre table ne remarque rien.

Comment fonctionne une API : requête et réponse

Presque toutes les API fonctionnent sur la même boucle simple : un client envoie une requête, le serveur renvoie une réponse. Tout le reste n'est que détail par-dessus ce schéma. Passez en revue les éléments et le reste de cet article s'emboîtera.

La requête

Une requête est un message que votre programme envoie à l'API pour indiquer ce qu'il veut. Une requête d'API web typique contient quatre éléments : quelle adresse contacter (l'endpoint), quel type d'action vous souhaitez (la méthode), qui vous êtes (l'authentification), et parfois un corps de données que vous envoyez.

La réponse

La réponse est ce qui revient. Elle comprend généralement un code de statut qui vous indique comment cela s'est passé (200 signifie succès, 404 signifie introuvable, 401 signifie que vous n'étiez pas autorisé) et un corps contenant les données demandées, le plus souvent formatées en JSON. Votre code lit cette réponse et en fait quelque chose d'utile.

Les endpoints

Un endpoint est une adresse spécifique que vous appelez pour accéder à une ressource ou une action particulière. Si l'API est le menu, les endpoints sont les plats individuels. Une API météo peut exposer un endpoint pour les conditions actuelles et un autre pour les prévisions à cinq jours. Les endpoints entrent généralement dans quelques formes familières :

• Les endpoints de ressource renvoient une chose spécifique, comme un profil utilisateur unique ou un produit.
• Les endpoints de collection renvoient un groupe de choses, comme une liste de tous les produits.
• Les endpoints d'action effectuent une opération, comme traiter un paiement ou envoyer un e-mail.
• Les endpoints de recherche vous permettent d'interroger et de filtrer, comme trouver toutes les commandes passées cette semaine.

Les méthodes

La méthode indique à l'API ce que vous avez l'intention de faire avec un endpoint. Les API web empruntent ces verbes directement à HTTP, et quatre d'entre eux couvrent l'essentiel de ce que vous écrirez :

• GET lit des données sans rien modifier (récupérer un profil).
• POST crée quelque chose de nouveau (soumettre une nouvelle commande).
• PUT met à jour quelque chose d'existant (modifier un profil).
• DELETE supprime quelque chose (annuler une commande).

L'authentification

La plupart des API utiles ont besoin de savoir qui appelle avant de répondre. L'authentification est l'API qui vérifie votre identité à l'entrée. La forme la plus simple est une clé d'API, une longue chaîne secrète que vous incluez dans chaque requête et qui identifie votre compte, comme une clé de maison qui ouvre une porte spécifique. Les tokens vont plus loin : ils se comportent davantage comme une carte à puce qui contient également des informations sur ce que vous êtes autorisé à faire, et des standards comme OAuth 2.0 les utilisent pour un accès plus riche avec gestion des permissions. Le bon choix est un équilibre. Une clé d'API basique suffit pour un outil interne simple, tandis qu'une application publique orientée utilisateur nécessite généralement les garanties plus solides offertes par les tokens et OAuth.

JSON : le format que parlent la plupart des réponses

Quand une API répond, elle doit formater les données pour que votre programme puisse les lire de manière fiable. JSON (JavaScript Object Notation) est devenu la norme par défaut parce qu'il est compact, lisible par l'homme et pris en charge par tous les langages modernes. Il représente les données sous forme de paires clé-valeur et de listes imbriquées, ce qui correspond bien aux objets avec lesquels la plupart des programmes travaillent déjà. Une petite réponse JSON pour un seul utilisateur peut ressembler à ceci :

{
  "id": 42,
  "name": "Ada Lovelace",
  "email": "[email protected]",
  "active": true
}

Assemblez les pièces et un aller-retour complet se lit presque comme une phrase : envoyer une requête GET, à l'endpoint users, avec votre clé d'API, et recevoir du JSON. Voici cette même idée sous forme d'un appel en une ligne que vous pourriez exécuter depuis un terminal, plus le type de réponse qu'il renvoie.

# GET a user, sending an API key as a header
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.example.com/users/42"

Le serveur lit la requête, confirme la clé, recherche l'utilisateur 42 et répond avec l'objet JSON ci-dessus. Voilà l'intégralité du mécanisme derrière la plupart des API que vous toucherez jamais.

Types d'API : REST, SOAP, GraphQL et webhooks

Les API suivent une poignée de styles communs. Elles font toutes le travail de requête et réponse, mais elles diffèrent par leur degré de rigidité, la façon dont vous demandez des données et la façon dont elles reviennent. Quatre styles couvrent la grande majorité de ce que vous rencontrerez.

REST

REST (Representational State Transfer) est le style dominant sur le web moderne. C'est moins un protocole strict qu'un ensemble de conventions : utiliser des méthodes HTTP simples sur des endpoints bien nommés, garder chaque requête autonome, et renvoyer des données dans un format simple comme JSON. REST est populaire parce qu'il est accessible et sans état (stateless), ce qui signifie que chaque requête porte tout ce dont le serveur a besoin et que le serveur ne garde aucun souvenir des appels précédents. Cela rend les API REST faciles à mettre en cache, à faire évoluer et à apprendre, ce qui explique pourquoi la plupart des API publiques que vous rencontrez sont RESTful.

SOAP

SOAP (Simple Object Access Protocol) est le cousin plus ancien et plus strict. Là où REST est flexible, SOAP impose un contrat rigide : les messages sont toujours en XML et doivent suivre une structure formelle. Cette rigueur est une fonctionnalité dans des contextes réglementés et à enjeux élevés. SOAP possède de solides standards intégrés pour la sécurité, les transactions et la fiabilité, de sorte qu'il apparaît encore dans des environnements d'entreprise comme la banque et le traitement des paiements, où la messagerie garantie et traçable compte plus que la commodité.

GraphQL

GraphQL, développé chez Facebook en 2012, adopte une approche différente. Au lieu de nombreux endpoints renvoyant chacun une forme fixe de données, il expose un seul endpoint et permet au client de demander exactement les champs qu'il veut. Les avantages suivent directement : vous arrêtez de récupérer des données dont vous n'avez pas besoin, vous pouvez tirer des éléments connexes en un seul aller-retour plutôt que plusieurs, et un schéma typé documente précisément ce qui est disponible avant même d'envoyer une requête. Cette précision rend GraphQL attrayant pour les applications complexes avec de nombreux écrans qui ont chacun besoin de tranches légèrement différentes des mêmes données.

Les webhooks

Les webhooks inversent la direction habituelle. Avec REST, SOAP et GraphQL, votre application demande et le serveur répond ; avec un webhook, le serveur informe votre application dès qu'un événement se produit, sans qu'on lui demande. Vous enregistrez une URL, et quand un événement survient (un paiement est validé, un build se termine, un formulaire est soumis), le service envoie une requête à votre URL avec les détails. Pensez à la différence entre téléphoner à plusieurs reprises à la cuisine pour demander si votre commande est prête et la cuisine qui sonne simplement une cloche quand c'est prêt. Les webhooks sont la façon standard d'obtenir des mises à jour en temps réel sans interroger une API en permanence.

Exemples d'API concrets

La façon la plus claire de faire mémoriser la définition d'une API est d'en nommer quelques-unes que vous avez presque certainement utilisées :

• Paiements. Quand une page de paiement débite votre carte, elle appelle l'API d'un fournisseur de paiement en arrière-plan. Le magasin ne touche jamais vos données de carte brutes ; il demande à l'API de gérer la transaction et attend une réponse approuvée ou refusée.
• Cartes. Une application de livraison qui affiche une carte en direct et une heure d'arrivée estimée récupère des tuiles, des itinéraires et des distances depuis une API cartographique plutôt que de construire sa propre carte du monde.
• Se connecter avec Google ou Apple. Ces boutons utilisent une API d'authentification pour qu'une application puisse confirmer qui vous êtes sans jamais voir votre mot de passe.
• Météo. Les prévisions dans l'application météo de votre téléphone proviennent de l'API d'un fournisseur météo, les mêmes données revendues à l'agriculture, à la logistique et à l'organisation d'événements.
• Réseaux sociaux et streaming. Publier depuis une application tierce, ou obtenir une playlist personnalisée, passe par des API qui lisent et écrivent des données au nom de la plateforme.

Pourquoi les API sont importantes

Les API sont la raison pour laquelle les logiciels modernes sont construits à partir de pièces plutôt que de zéro. Aucune équipe n'a besoin d'écrire son propre processeur de paiement, son moteur cartographique ou son système d'authentification quand une API bien documentée fait le travail en quelques appels. Cela permet aux entreprises de livrer plus vite et de se concentrer sur ce qui rend leur produit différent plutôt que de reconstruire des problèmes déjà résolus.

Elles créent aussi une vraie valeur commerciale. Les API permettent à une entreprise de s'intégrer dans des écosystèmes partenaires, d'ouvrir de nouveaux canaux de distribution et d'atteindre des segments de clientèle qu'elle ne pourrait pas servir seule. De nombreuses organisations traitent désormais leurs données et services comme des produits à part entière : une entreprise météo vend ses prévisions via une API, une banque expose les données de compte aux applications fintech, et les deux transforment des systèmes existants en revenus. Les API unifient également la vue client en brisant les silos de données, de sorte qu'une application, un site web et un chatbot peuvent tous présenter les mêmes informations cohérentes et à jour.

Quand un site n'a pas d'API : l'API de scraping

Voici le problème. Beaucoup de données que vous pourriez vouloir se trouvent sur un site public qui n'offre aucune API officielle. L'information est là, sur la page, mais il n'y a pas d'endpoint propre à appeler ni de JSON qui vous attend. La réponse traditionnelle est le web scraping : récupérer le HTML de la page et en extraire les valeurs vous-même. Cela fonctionne jusqu'à ce que le site rende le contenu avec JavaScript, bloque les visiteurs inconnus, envoie un CAPTCHA ou change sa mise en page, moment où un simple fetch se transforme en problème de maintenance permanent.

Une API de scraping comble l'écart en enveloppant tout cela derrière un seul endpoint. Au lieu de gérer vous-même des navigateurs, des proxies et des tentatives, vous envoyez une requête qui nomme l'URL que vous voulez, et vous recevez la page en retour comme une réponse propre, exactement la boucle requête-réponse que toutes les autres API utilisent. En effet, cela donne à un site sans API une interface semblable à une API : vous l'appelez de la même façon que vous appelleriez un service météo ou de paiement, et les parties complexes de la récupération d'une vraie page restent de l'autre côté du contrat.

Une fois qu'une page revient comme une réponse prévisible, tout ce que vous avez appris ci-dessus s'applique. Vous pouvez parser le HTML avec une bibliothèque, demander les données avec l'aide de Python ou de Node.js, et alimenter le résultat dans votre propre application exactement comme s'il était arrivé depuis un endpoint JSON documenté. Le site web devient juste une autre API que votre code sait comment appeler.

Scraper de manière responsable

Traiter un site web comme une API ne supprime pas votre responsabilité quant à la façon dont vous l'utilisez. Tenez-vous aux données publiques, lisez et respectez les conditions d'utilisation du site et son robots.txt, identifiez vos requêtes honnêtement, et maintenez votre taux de requêtes raisonnable pour ne pas surcharger les serveurs de quelqu'un d'autre. Une API de scraping gérée vous aide à rester poli en répartissant et en cadençant les requêtes pour vous, mais le jugement sur ce qu'il faut collecter, et à quelle intensité cibler un site, reste le vôtre.

Foire aux questions

Qu'est-ce qu'une API en termes simples ?

Une API est un ensemble de règles permettant à deux logiciels de communiquer entre eux. Un programme envoie une requête demandant des données ou une action, et l'autre envoie une réponse dans un format convenu. Comme un serveur qui porte votre commande à la cuisine et rapporte la nourriture, l'API gère la conversation pour qu'aucun des deux côtés n'ait besoin de savoir comment l'autre fonctionne en interne.

Quelle est la différence entre une API et un site web ?

Un site web est conçu pour les personnes : il renvoie du HTML stylisé pour un navigateur afin qu'un être humain puisse le lire. Une API est conçue pour les programmes : elle renvoie des données structurées, généralement du JSON, que d'autres logiciels peuvent lire directement. Une API de scraping se situe entre les deux, récupérant une page destinée aux humains et la renvoyant comme une réponse prévisible que votre code peut traiter.

Quels sont les principaux types d'API ?

Les styles les plus courants sont REST, SOAP, GraphQL et les webhooks. REST est le standard flexible et largement utilisé pour les services web. SOAP est un protocole plus strict, basé sur XML, privilégié dans les entreprises et la finance. GraphQL permet aux clients de demander exactement les champs dont ils ont besoin depuis un seul endpoint. Les webhooks inversent le flux pour qu'un serveur puisse pousser des mises à jour en temps réel vers votre application quand un événement se produit.

Qu'est-ce que JSON et pourquoi les API l'utilisent-elles ?

JSON (JavaScript Object Notation) est un format léger basé sur du texte pour représenter des données sous forme de paires clé-valeur et de listes. Les API le privilégient parce qu'il est compact, facile à lire pour les humains, et pris en charge par tous les langages de programmation modernes, ce qui rend les réponses simples à envoyer, stocker et parser.

Ai-je besoin d'une clé d'API pour utiliser une API ?

Souvent, oui. De nombreuses API nécessitent une clé d'API ou un token pour pouvoir identifier votre compte, contrôler l'accès et suivre l'utilisation. Vous incluez la clé dans chaque requête, comme montrer une pièce d'identité à une porte. Certaines API ouvertes permettent une utilisation limitée sans clé, mais la plupart des services de production en attendent une.

Comment utiliser un site web qui n'a pas d'API ?

Vous pouvez utiliser une API de scraping, qui enveloppe le site derrière un seul endpoint. Vous envoyez une requête nommant la page que vous voulez, et le service la récupère en gérant le rendu, la rotation d'IP et les blocages pour vous, puis renvoie le HTML comme une réponse propre. À partir de là vous parsez les données exactement comme vous le feriez avec n'importe quelle API standard.

TA

Thomas Adewale

Rédacteur technique · Crawlbase

Rédacteur technique chez Crawlbase, il couvre les réseaux de proxys, les stratégies de rotation et la tuyauterie qui rend le crawling fiable à grande échelle.