Параметры пути, параметры запроса и тело

Что мы изучим?#

Клиенту нужно сказать серверу, что именно он хочет. Для этого есть три способа:

Зачем это нужно?#

В следующем уроке мы напишем первый сервер, и в FastAPI каждый из трёх способов определяется по-своему. Если не понимать разницу, информация попадает не туда: идентификатор — в тело, а пароль — в URL. А каждый настоящий API, которым вы будете пользоваться (GitHub, погода, платежи), использует все три.

Объяснение с основ#

Параметр пути — «какой именно?»#

Переменная часть внутри пути, которая идентифицирует конкретный ресурс:

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

Когда: когда вы идентифицируете один элемент (обычно по id). Без параметра путь неполный.

Параметры запроса — «как? сколько? отфильтровать по чему?»#

Пары key=value после ?, разделённые &:

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

Когда: фильтрация, сортировка, постраничный вывод (Pagination) и опции. Обычно необязательны: GET /students работает и без них и просто возвращает всё.

Тело — «вот данные»#

Сами данные, в теле запроса, почти всегда в JSON:

POST /students
Content-Type: application/json

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

Когда: когда вы отправляете данные для создания или обновления (POST, PUT). Можно отправлять сложные структуры (списки, вложенные объекты) и большие объёмы. У GET и DELETE тела нет.

Как решить?#

Кодирование URL (URL Encoding)#

В URL пробелы и специальные символы нельзя писать «как есть». Пробел становится %20 (или +), & внутри значения становится %26, а неанглийские буквы (например, на иврите или русском) кодируются в байты (%D7%93...). Кодирование за нас делают браузер и библиотеки — но важно понимать, зачем оно существует.

Разбор адреса#

/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)

• Путь идентифицирует, какой ресурс: оценки студента 7.
• Строка запроса начинается после ?, и параметры разделяются &. Она говорит, как: какой семестр и сколько результатов.

Все три в одном запросе#

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

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

В следующем уроке мы увидим, как FastAPI автоматически принимает все три — и кладёт каждый в параметр нашей функции.

Типичная ошибка#

Ошибка 1: идентификатор в строке запроса вместо пути — или наоборот.

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

Соглашение: конкретный элемент — в пути (/students/7), фильтрация — в строке запроса (/students?city=Haifa).

Ошибка 2: значение с пробелами и & «как есть» в адресе.

/search?q=rock & roll

Пробелы ломают адрес, а & воспринимается как начало нового параметра. Значение нужно закодировать: q=rock+%26+roll.

Ошибка 3: забыть, что всё в URL — строка. "7" ≠ 7. Сравнение if student_id == 7, когда student_id пришёл из URL как "7", → False. (FastAPI преобразует за нас, если мы укажем тип.)

Ошибка 4: чувствительная информация в URL. GET /login?user=dana&password=1234. URL сохраняется в истории браузера, в логах сервера и в ссылках, которые вы отправляете. Пароли — только в теле (и всегда через HTTPS).

Практика#

Упражнения опираются только на то, что пройдено в этом уроке и в предыдущих. Сначала попробуйте сами, и только потом открывайте решение.

Упражнение 1: Куда идёт каждый кусок данных?#

Для каждого запроса — являются ли данные параметром пути, параметром запроса или телом?

1. Идентификатор студента, которого вы хотите получить.
2. Фильтрация студентов по городу.
3. Имя и возраст нового студента.
4. Сколько результатов возвращать на страницу.
5. Обновлённые данные существующего студента.

Упражнение 2: Разбор адреса#

Разберите адрес: что является путём, какой в нём идентификатор и каковы параметры запроса?

https://api.kodkod.dev/students/7/grades?semester=2&limit=5

Упражнение 3: Строим адрес#

Напишите адреса для следующих запросов к серверу https://api.x.com:

1. Все студенты из Хайфы.
2. Студенты из Хайфы, первые десять.
3. Студент 7.
4. Оценки студента 7 в семестре 1.

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

Упражнение 4: Все три в одном запросе#

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

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

Определите параметр пути, параметр запроса и тело и объясните, почему каждый кусок данных находится на своём месте. Какова роль заголовка Content-Type?

Упражнение 5: Что не идёт в адрес?#

Для каждого адреса — в чём проблема и как сделать правильно?

1. GET /students?id=7
2. GET /students/city/Haifa
3. GET /login?user=dana&password=1234
4. GET /search?q=rock & roll

Итоги#

• Параметр пути (/students/7) — какой ресурс. Часть пути.
• Параметры запроса (?city=Haifa&limit=10) — фильтрация, сортировка, постраничный вывод, опции. Обычно необязательны.
• Тело (JSON) — данные для создания и обновления (POST, PUT). У GET и DELETE тела нет.
• Всё в URL — строка. Строку запроса нужно правильно кодировать (пробелы, & и неанглийские буквы).
• Не кладите пароли и чувствительную информацию в URL.
• В следующих уроках FastAPI будет автоматически разбирать все три, включая преобразование типов.

Официальная документация#

• MDN — What is a URL?
• MDN — HTTP messages: Body