Chapitre 02 — Faites vos premiers appels API6 min de lecture

Anatomie d’une requête

Qu'y a-t-il dans une requête ?

Dans la leçon précédente, vous avez fait votre premier appel API en cliquant sur un lien. Votre navigateur a envoyé une requête à wttr.in et a reçu du JSON en retour. Simple.

Mais cette requête contenait plus qu'une simple URL. Chaque requête API a quelques éléments clés, et les comprendre vous aidera à lire la documentation API, rédiger de meilleurs specs, et avoir des conversations plus productives avec vos développeurs.

L'URL (où aller)

Vous connaissez déjà cette partie. L'URL indique au serveur ce que vous demandez. Utilisons une API publique appelée DummyJSON qui fournit de fausses données utilisateur (utile pour tester et apprendre) :

https://dummyjson.com/users?limit=2
URL de baseCheminParamètres de requête
  • L'URL de base est l'adresse du serveur, comme une adresse postale pour un bâtiment.
  • Le chemin indique au serveur quelle ressource vous voulez. Ici, /users signifie "l'endpoint des utilisateurs."
  • Le paramètre de requête est une instruction supplémentaire. limit=2 dit au serveur "donne-moi seulement deux utilisateurs."

Essayez : 👉 cliquez ici pour ouvrir cette API dans un nouvel onglet

Vous devriez voir une réponse JSON avec deux utilisateurs (nom, email, âge, etc.). Maintenant, la partie intéressante : les paramètres de requête vous permettent de personnaliser ce que vous recevez. Vous pouvez les combiner avec & :

https://dummyjson.com/users?limit=3&select=firstName,email,age&sortBy=age&order=desc
URL de baseCheminParamètres de requête

Ça dit : "Donne-moi 3 utilisateurs, mais seulement leur nom, email et âge, triés par âge du plus vieux au plus jeune." Même endpoint, paramètres différents, résultat différent.

Essayez : 👉 ouvrez cette URL dans un nouvel onglet et comparez avec la première. La structure est identique, mais les données sont filtrées et triées.

Les paramètres de requête servent à filtrer, trier et personnaliser ce que vous recevez d'une API. Vous les verrez partout.

La méthode (quoi faire)

L'URL dit où aller. La méthode dit quoi faire une fois arrivé.

Il y a quatre méthodes que vous verrez tout le temps :

GET : lire des données. "Donne-moi la liste des utilisateurs." C'est la plus courante. Quand vous tapez une URL dans votre navigateur, vous envoyez une requête GET. Chaque fois que vous chargez une page web, c'est un GET. En fait, un navigateur ne peut envoyer que des requêtes GET. Il est fait pour lire, pas pour créer ou supprimer.

POST : créer quelque chose. "Crée une nouvelle commande." Vous envoyez des données au serveur et lui demandez de créer une nouvelle ressource.

PUT : modifier quelque chose. "Mets à jour l'adresse email de l'utilisateur #8421." Vous modifiez une ressource existante.

DELETE : supprimer quelque chose. "Annule la commande #5678." Vous demandez au serveur de supprimer une ressource.

Pour POST, PUT et DELETE, vous avez besoin d'un outil qui vous permet de choisir la méthode. Les développeurs utilisent des outils comme Postman ou similaires. On explorera ça dans un chapitre ultérieur.

Pensez-y comme ça. Le même endpoint peut faire des choses différentes selon la méthode :

GET/orders/5678 → lire la commande #5678
PUT/orders/5678 → modifier la commande #5678
DELETE/orders/5678 → annuler la commande #5678
MéthodeChemin

L'URL est la même. La méthode change complètement le sens. C'est comme la différence entre regarder un document, le modifier, ou le supprimer.

Les headers (métadonnées)

Les headers sont des informations supplémentaires attachées à la requête. Ils ne contiennent pas les données que vous demandez. Ils décrivent comment la requête doit être traitée.

Les plus courants que vous verrez dans la documentation API :

  • Content-Type: application/json dit au serveur "les données que j'envoie sont du JSON"
  • Authorization: Bearer sk_live_abc123 dit au serveur qui vous êtes (on verra ça dans le chapitre sur l'authentification)
  • Accept: application/json dit au serveur "renvoie-moi du JSON s'il te plaît"

Vous ne définissez généralement pas les headers manuellement. L'application ou l'outil que vous utilisez s'en charge. Mais vous les verrez dans la documentation API, et maintenant vous savez ce qu'ils sont : des métadonnées sur la requête, pas la requête elle-même.

Le body (les données que vous envoyez)

Toutes les requêtes n'ont pas de body. Quand vous faites un GET, vous posez juste une question. Il n'y a rien à envoyer.

Mais quand vous faites un POST ou un PUT, vous envoyez des données au serveur. Ces données vont dans le body de la requête. Et c'est généralement du JSON.

Par exemple, pour ajouter un nouvel utilisateur sur DummyJSON :

POSThttps://dummyjson.com/users/add
MéthodeChemin

Avec ce body :

{ "firstName": "Bob", "lastName": "Chen", "email": "bob@startup.io", "age": 32 }
Corps

Vous dites au serveur : "Crée un nouvel utilisateur avec ce nom, cet email et cet âge." Le serveur traite la demande et renvoie une réponse (généralement l'utilisateur créé avec un id généré pour lui).

Tout assembler

Voici à quoi ressemble une requête API complète, avec toutes les parties :

POSThttps://api.myapp.com/orders
Content-Type: application/json
Authorization: Bearer sk_live_abc123
{ "customer_id": "usr_8a3b2c1d", "items": [ { "product": "Wireless Mouse", "quantity": 1 } ] }
MéthodeCheminEn-têtesCorps

Lisez-le comme une phrase : "Crée (POST) une nouvelle commande (/orders) pour ce client avec ces articles (body), et voici mes identifiants (header Authorization)."

C'est une requête complète. URL, méthode, headers, body. Maintenant, quand vous les verrez dans la documentation API, vous saurez exactement ce que fait chaque partie.

Points clés

  • L'URL dit où aller (URL de base + chemin + paramètres de requête)
  • La méthode dit quoi faire (GET, POST, PUT, DELETE)
  • Les headers sont des métadonnées sur la requête (authentification, type de contenu)
  • Le body contient les données que vous envoyez (utilisé avec POST et PUT, toujours en JSON)