kodkod | Cours d'introduction
Docs
kodkod | Cours d'introduction
Backend et FastAPI

Path Params, Query Parameters et Body

Objectifs de la leçon
  • Distinguer un Path Parameter, un Query Parameter et un body
  • Choisir la bonne façon de transmettre chaque type d’information
  • Construire une URL avec une query correcte, et comprendre pourquoi les caractères spéciaux sont encodés
  • Reconnaître dans une vraie requête ce qui est dans le chemin, ce qui est dans la query et ce qui est dans le body

Qu’allons-nous apprendre ?

Un client doit dire au serveur ce qu’il veut exactement. Il a trois façons de le faire :

FaçonOùExemple
Path ParameterUne partie du chemin lui-même/students/7
Query ParametersAprès ? dans l’URL/students?city=Haifa&limit=10
BodyDans le corps de la requête (JSON){"name": "Dana", "age": 24}

Pourquoi en avons-nous besoin ?

Dans la leçon suivante, nous écrirons le premier serveur, et dans FastAPI chacun des trois se définit d’une façon différente. Si vous ne comprenez pas la différence, vous mettez l’information au mauvais endroit : un identifiant dans le body, ou un mot de passe dans l’URL. Et toute vraie API que vous utiliserez (GitHub, météo, paiements) utilise les trois.

Explication à partir des bases

Path Parameter — « lequel ? »

Une partie variable dans le chemin, qui identifie une ressource précise :

GET /students/7
              └─ path parameter: which student
GET /users/octocat/repos
           └─ path parameter: which user

Quand : quand on identifie un seul élément (généralement par son id). Sans le paramètre, le chemin n’est pas complet.

Query Parameters — « comment ? combien ? filtré par quoi ? »

Des paires key=value après ?, séparées par & :

GET /students?city=Haifa&min_age=20&limit=10
             └──────────── query string ────────┘
                key=value & key=value & key=value

Quand : le filtrage, le tri, la pagination (Pagination), et les options. Généralement facultatifs : GET /students fonctionne aussi sans eux, et renvoie simplement tout.

Body — « voici les données »

Les données elles-mêmes, dans le corps de la requête, presque toujours en JSON :

POST /students
Content-Type: application/json

{"name": "Dana", "age": 24, "email": "dana@mail.com"}

Quand : quand on envoie des données pour créer ou mettre à jour (POST, PUT). On peut envoyer des structures complexes (listes, objets imbriqués) et de grandes quantités. GET et DELETE n’ont pas de body.

Comment décider ?

QuestionFaçon
Identifie quel élément ?Path — /students/7
Filtre, trie, limite la quantité, une option d’affichage ?Query — ?city=Haifa&sort=age
Les données d’une ressource que l’on crée ou met à jour ?Body — JSON
Une information sensible (un mot de passe, un jeton) ?Jamais dans l’URL (elle est enregistrée dans les journaux et dans l’historique du navigateur). Le body ou les en-têtes
Analogie : commander une pizza par téléphone

« J’appelle la succursale de Haïfa » (Path : quel endroit exactement). « Dites-moi les offres, végan uniquement, les moins chères d’abord » (Query : filtrage et tri de ce que je demande). « Je veux commander : une pizza familiale, olives, champignons, au 10 rue Herzl » (Body : tous les détails de ce qui est créé).

L’encodage d’URL (URL Encoding)

Dans une URL, les espaces et les caractères spéciaux ne sont pas autorisés « tels quels ». Un espace devient %20 (ou +), un & dans une valeur devient %26, et les lettres non anglaises (comme l’hébreu ou les lettres accentuées) sont encodées en octets (%D7%93...). Le navigateur et les bibliothèques font l’encodage pour nous — mais il est important de comprendre pourquoi il existe.

Décomposer une adresse

/students/7/grades?semester=2&limit=5

path   ->  students / 7 / grades   (the grades of student 7)
query  ->  semester = 2            (a filter)
           limit    = 5            (how many)
  • Le Path identifie quelle ressource : les notes de l’étudiant 7.
  • La Query commence après ?, et chaque paramètre est séparé par &. Elle dit comment : quel semestre, et combien de résultats.

Les trois dans une seule requête

PUT /students/7?notify=true
Content-Type: application/json

{"name": "Dana Cohen", "age": 25}
PartieValeurPourquoi ici
Path7Quel étudiant — fait partie de l’identité de la ressource
Querynotify=trueUne option de la requête — ne fait pas partie des données
Body{"name": ..., "age": ...}Les nouvelles données elles-mêmes
HeaderContent-Type: application/jsonDans quel format est le corps

Dans la leçon suivante, nous verrons comment FastAPI reçoit les trois automatiquement — et place chacun dans un paramètre de notre fonction.

Erreur courante

Erreur 1 : un identifiant dans la query au lieu du chemin, ou l’inverse.

GET /students?id=7          ← works, but not the convention for ONE resource
GET /students/city/Haifa    ← "Haifa" is a filter, not a resource id

La convention : un élément précis dans le chemin (/students/7), le filtrage dans la query (/students?city=Haifa).

Erreur 2 : une valeur avec des espaces et un & « telle quelle » dans l’adresse.

/search?q=rock & roll

Les espaces cassent l’adresse, et le & est interprété comme le début d’un nouveau paramètre. La valeur doit être encodée : q=rock+%26+roll.

Erreur 3 : oublier que tout ce qui est dans l’URL est une chaîne. "7" ≠ 7. Une comparaison if student_id == 7 quand student_id est arrivé de l’URL sous forme de "7" → False. (FastAPI fera la conversion pour nous, si nous définissons un type.)

Erreur 4 : des informations sensibles dans l’URL. GET /login?user=dana&password=1234. L’URL est enregistrée dans l’historique du navigateur, dans les journaux du serveur, et dans les liens que vous envoyez. Les mots de passe : uniquement dans le body (et toujours en HTTPS).

Exercices

Les exercices n’utilisent que ce qui a été vu dans cette leçon et les précédentes. Essayez d’abord seul, et n’ouvrez la solution qu’ensuite.

Exercice 1: Où va chaque donnée ?

Pour chaque requête — la donnée est-elle un Path Parameter, un Query Parameter ou un body ?

  1. L’identifiant de l’étudiant que vous voulez obtenir.
  2. Filtrer les étudiants par ville.
  3. Le nom et l’âge d’un nouvel étudiant.
  4. Combien de résultats renvoyer par page.
  5. Les données mises à jour d’un étudiant existant.
Afficher la solution
  1. Path — identifie quelle ressource : /students/7.
  2. Query — le filtrage : /students?city=Haifa.
  3. Body — les données d’une nouvelle ressource, en JSON.
  4. Query — une option : ?limit=10.
  5. Body (et l’identifiant dans le Path) : PUT /students/7 avec un corps.

La règle : Path — quelle ressource. Query — filtrage, tri et pages. Body — les données elles-mêmes.

Exercice 2: Décomposer une adresse

Décomposez l’adresse : quel est le chemin, quel est l’identifiant qu’il contient, et quels sont les Query Parameters ?

https://api.kodkod.dev/students/7/grades?semester=2&limit=5
Afficher la solution
PartieValeurSignification
Path/students/7/gradesLes notes de l’étudiant 7
Identifiant dans le Path7Quel étudiant
Querysemester=2Un filtre — le semestre 2
Querylimit=5Combien de résultats — 5

La query commence après ?, et chaque paramètre est séparé par &.

Exercice 3: Construire une adresse

Écrivez les adresses des requêtes suivantes, vers le serveur https://api.x.com :

  1. Tous les étudiants de Haïfa.
  2. Les étudiants de Haïfa, les dix premiers.
  3. L’étudiant 7.
  4. Les notes de l’étudiant 7 au semestre 1.
Afficher la solution
1. https://api.x.com/students?city=Haifa
2. https://api.x.com/students?city=Haifa&limit=10
3. https://api.x.com/students/7
4. https://api.x.com/students/7/grades?semester=1

L’identifiant va dans le chemin, et les filtres dans la query — après ?, et reliés par &.

Exercice 4: Les trois dans une seule requête

PUT /students/7?notify=true
Content-Type: application/json

{"name": "Dana Cohen", "age": 25}

Identifiez le Path Parameter, le Query Parameter et le body, et expliquez pourquoi chaque donnée est à sa place. Quel est le rôle de l’en-tête Content-Type ?

Afficher la solution
  • Path : 7 — quel étudiant est mis à jour. Cela fait partie de l’identité de la ressource.
  • Query : notify=true — une option de la requête : comment l’effectuer. Cela ne fait pas partie des données de l’étudiant.
  • Body : {"name": "Dana Cohen", "age": 25} — les nouvelles données elles-mêmes.
  • Content-Type: application/json — dit au serveur dans quel format est le corps, pour qu’il sache comment le lire.

Exercice 5: Qu’est-ce qui ne va pas dans l’adresse ?

Pour chaque adresse — quel est le problème, et comment faire correctement ?

1. GET /students?id=7
2. GET /students/city/Haifa
3. GET /login?user=dana&password=1234
4. GET /search?q=rock & roll
Afficher la solution
  1. L’identifiant d’un seul élément va dans le chemin : GET /students/7. La query est destinée au filtrage.
  2. « Haifa » est un filtre, pas l’identifiant d’une ressource : GET /students?city=Haifa.
  3. Un mot de passe dans l’adresse est enregistré dans l’historique du navigateur, dans les journaux du serveur et dans les liens que vous envoyez. Les mots de passe — uniquement dans le body, et toujours en HTTPS.
  4. Des espaces et un & dans une valeur cassent l’adresse : le & est interprété comme le début d’un nouveau paramètre. La valeur doit être encodée (URL Encoding) : q=rock+%26+roll. En pratique, le navigateur et les bibliothèques font l’encodage pour nous.

Résumé

  • Path Parameter (/students/7) — quelle ressource. Fait partie du chemin.
  • Query Parameters (?city=Haifa&limit=10) — filtrage, tri, pagination, options. Généralement facultatifs.
  • Body (JSON) — les données pour créer et mettre à jour (POST, PUT). GET et DELETE n’ont pas de body.
  • Tout ce qui est dans l’URL est une chaîne. Une query doit être correctement encodée (espaces, & et lettres non anglaises).
  • Ne mettez pas de mots de passe ni d’informations sensibles dans l’URL.
  • Dans les leçons suivantes, FastAPI décodera les trois automatiquement, y compris la conversion des types.

Documentation officielle