À quoi ressemble une doc API
Le mode d'emploi de chaque API
Vous savez envoyer des requêtes API, lire des réponses JSON et vous authentifier. Mais quand vous vous asseyez pour travailler avec une nouvelle API, comment savez-vous quels endpoints existent, quels paramètres envoyer, ou à quoi ressemblera la réponse ?
C'est à ça que sert la documentation API. C'est le mode d'emploi qui vous dit tout ce que l'API peut faire et exactement comment l'utiliser.
Pensez-y comme un menu de restaurant. Vous n'entreriez pas dans un restaurant en criant "donnez-moi à manger." Vous regarderiez le menu, verriez ce qui est disponible, choisiriez les options (à point ou bien cuit ?), puis passeriez une commande précise. La documentation API, c'est le menu.
Les sections que vous trouverez partout
Chaque documentation API suit à peu près la même structure. Une fois que vous l'avez vue deux ou trois fois, vous pouvez naviguer n'importe quelle doc. Voici les sections qui reviennent systématiquement.
1. Base URL
C'est le point de départ de toutes les requêtes. Chaque endpoint se construit dessus.
La base URL de Stripe est https://api.stripe.com. Celle de Twilio est https://api.twilio.com. Celle de NewsAPI est https://newsapi.org. Vous verrez la base URL tout en haut de la doc, et chaque endpoint commence par elle.
2. Liste des endpoints
C'est le cœur de la doc. Elle liste chaque opération possible : récupérer une liste d'utilisateurs, créer une commande, supprimer un abonnement. Généralement organisée par ressource (Users, Orders, Products).
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/customers | Lister tous les clients |
| GET | /v1/customers/:id | Récupérer un client |
| POST | /v1/customers | Créer un client |
| DELETE | /v1/customers/:id | Supprimer un client |
Cela devrait vous rappeler le Chapitre 3. La doc détaille la méthode et le chemin exacts pour chaque opération, plus une courte description.
3. Section authentification
La doc explique toujours comment s'authentifier. Cette section vous dit quel type d'identifiants il vous faut (API key, token, OAuth), où les obtenir et où les placer dans votre requête.
Par exemple, la doc de Stripe vous demande d'envoyer votre API key comme Bearer token :
D'autres API (comme NewsAPI) utilisent un query parameter à la place. La doc vous indique quelle approche utiliser.
4. Paramètres
Pour chaque endpoint, la doc liste les paramètres que vous pouvez envoyer. Certains sont obligatoires (la requête échoue sans eux), d'autres sont optionnels (ils permettent d'affiner les résultats).
Voici à quoi ressemble le tableau de paramètres pour l'endpoint /everything de NewsAPI (un endpoint de recherche d'articles d'actualité) :
| Parameter | Type | Required | Description |
|---|---|---|---|
| q | string | Yes | La requête de recherche (ex. 'bitcoin', 'Apple') |
| from | string | No | Date de début (ex. 2024-01-15) |
| sortBy | string | No | Ordre de tri : relevancy, popularity, ou publishedAt |
| pageSize | integer | No | Nombre de résultats par page (max 100) |
C'est le type de tableau que vous verrez sur chaque page d'endpoint. Il vous donne le nom, le type de données, si c'est obligatoire, et ce que ça fait. Vous utiliserez cet endpoint plus tard dans ce chapitre.
5. Exemples de requêtes et réponses
Une bonne doc vous montre des exemples complets : voici une requête que vous pouvez copier, et voici à quoi ressemble la réponse. C'est souvent la section la plus utile, car vous pouvez prendre l'exemple, remplacer les valeurs par les vôtres et l'exécuter.
Les vraies docs suivent ce schéma
Voyons comment cela se retrouve dans quelques API que vous pourriez rencontrer au travail :
| API | Base URL | Auth method | What it does |
|---|---|---|---|
| Stripe | https://api.stripe.com | Bearer token (API key) | Paiements, abonnements, factures |
| Twilio | https://api.twilio.com | Basic auth (account SID + token) | SMS, appels vocaux, vérification |
| NewsAPI | https://newsapi.org | Query parameter (apiKey=...) | Titres d'actualité et articles |
| OpenAI | https://api.openai.com | Bearer token (API key) | Génération de texte IA, création d'images |
Des API différentes, des usages différents, mais la doc suit toujours la même structure : base URL, endpoints, authentification, paramètres, exemples.
Par où commencer
Quand vous ouvrez une documentation API pour la première fois, voici un ordre pratique :
- Authentification. Trouvez comment obtenir vos identifiants et où les placer. Rien ne fonctionne sans ça.
- Liste des endpoints. Parcourez la barre latérale ou la table des matières. Trouvez la ressource qui vous intéresse (utilisateurs, commandes, messages).
- L'endpoint précis. Cliquez dessus. Lisez le tableau de paramètres et regardez l'exemple de requête.
- Testez l'exemple. Copiez-le, insérez vos identifiants et exécutez-le.
Vous n'avez pas besoin de lire toute la doc de bout en bout. Vous naviguez vers ce dont vous avez besoin, exactement comme vous ne lisez pas un menu de restaurant de la première à la dernière page. Vous allez directement à la section qui vous intéresse.
Points clés
- La documentation API est le mode d'emploi. Elle vous dit ce que l'API peut faire et comment l'utiliser.
- Chaque doc contient les mêmes sections principales : base URL, endpoints, authentification, paramètres et exemples.
- Vous ne lisez pas la doc de haut en bas. Vous cherchez la section dont vous avez besoin, en commençant par l'authentification.
- Une fois que vous avez navigué une documentation API, le schéma est le même partout.