HTTP на пальцах

методы, коды, заголовки, тело

Что это

HTTP — язык, на котором клиент и сервер разговаривают. Знать его целиком не нужно, но четыре вещи встречаются постоянно: метод, код ответа, заголовки и тело.

Это же язык, на котором отлаживают: «пришёл 404» или «отдаёт 500» — точное описание проблемы, с которым ИИ сразу понимает, где искать.

Как выглядит в коде

Настоящий обмен — запрос и ответ целиком:

curl -i http://127.0.0.1:8765/subs/7

HTTP/1.1 200 OK
server: uvicorn
content-length: 40
content-type: application/json

{"user_id":7,"cities":["Oslo","Bergen"]}

Первая строка — код. Дальше заголовки. Пустая строка отделяет их от тела.

Методы

Главное свойство GET — он не должен ничего менять. Это не формальность: браузеры, поисковики и кеши повторяют GET-запросы сами по себе. Если GET что-то создаёт, оно создастся несколько раз.

Коды ответов

Первая цифра говорит, кто виноват:

Шесть кодов, которые встретятся чаще всего:

Все эти коды в нашем примере настоящие:

curl -X POST .../subs/7 -d '{"city":"Tromsø"}'   → 201
curl -X POST .../subs/7 -d '{"city":"Tromsø"}'   → 409  (уже подписан)
curl -X POST .../subs/7 -d '{"city":"X"}'        → 422  (короче двух символов)

Заголовки

Служебные поля запроса и ответа. Знать надо три:

Authorization — тот самый заголовок, в котором едут секреты. Про него отдельно в статье 7.8.

Тело

Данные запроса или ответа. Почти всегда JSON. У GET тела обычно нет — параметры передают в адресе:

/subs?city=Oslo&limit=10

Это строка запроса: пары «ключ = значение» после знака вопроса.

Как сказать ИИ

Сервер отдаёт 500 на POST /subs/7 с телом {"city": ""}.
Должен отдавать 422. Вот обработчик: <код>.
Почему валидация не срабатывает?

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

Напиши curl-команды для проверки всех четырёх случаев:
успех, нет пользователя, повторная подписка, кривые данные.
С выводом кода ответа.

Последний запрос даёт готовый набор проверок — ровно то, что нужно для неудачных случаев из статьи 4.1.

На что смотреть

200 на ошибку. Ответ {"error": "не найден"} с кодом 200 ломает всех клиентов: они смотрят на код, а не читают текст.

500 на кривые данные. Значит, проверки нет и сервер падает на необработанном исключении. Правильный ответ — 400 или 422.

GET, который что-то меняет. Повторится сам, без участия пользователя.

Текст ошибки с лишним. Трейсбек в теле ответа показывает структуру проекта всем желающим. Подробности — в лог, клиенту короткое сообщение.

Код выбран наугад. 400 вместо 404, 403 вместо 401 — клиент не сможет отличить «не вошёл» от «вошёл, но не положено».

Шпаргалка