раздел 01

Как устроен запрос

Почти все веб-API работают поверх HTTP - того же протокола, по которому открываются сайты. Один обмен - это запрос от вас и ответ от сервиса. Разберём запрос по частям.

Метод: что вы хотите сделать

Метод говорит, какое действие вы просите. Четыре основных:

Метод	Что делает	Пример
`GET`	Получить данные	Получить список товаров
`POST`	Создать новое	Создать заказ
`PUT`	Обновить существующее	Изменить профиль
`DELETE`	Удалить	Удалить товар из корзины

URL (endpoint): куда обращаться

Endpoint - это адрес конкретной «двери» сервиса. Например https://api.example.com/v1/users - адрес для работы с пользователями. У одного сервиса много endpoint-ов под разные задачи.

Заголовки (headers): служебная информация

Заголовки - это пары «ключ: значение», которые идут вместе с запросом и описывают его. Тут передают формат данных (Content-Type: application/json), ключ доступа (Authorization), и прочую техническую информацию. Человеку их обычно видеть не нужно, но они есть в каждом запросе.

Тело (body): сами данные

Если вы что-то создаёте или обновляете (POST, PUT), данные кладут в тело запроса. У GET тела обычно нет - там всё нужное умещается в URL. Тело почти всегда в формате JSON.

Формат данных: JSON

JSON - это текстовый формат, в котором данные записаны как пары «ключ - значение». Его одинаково легко читают и люди, и программы. Выглядит так:

{
  "name": "Анна",
  "age": 30,
  "active": true
}

Метод + URL

Что сделать и над чем. GET /users - получить пользователей.

Заголовки

Служебные пары: формат данных, ключ доступа, язык.

Тело (JSON)

Сами данные при создании или обновлении. У GET его нет.

Ответ и коды статуса

В ответ сервис присылает данные (обычно JSON) и код статуса - трёхзначное число, по которому сразу видно, что произошло.

Код	Группа	Что значит
`200`	Успех	Всё хорошо, данные в ответе
`201`	Успех	Создано (часто после POST)
`400`	Ошибка клиента	Запрос составлен неправильно
`401`	Ошибка клиента	Не авторизован: нет или неверный ключ
`403`	Ошибка клиента	Доступ запрещён
`404`	Ошибка клиента	Не найдено: такого ресурса нет
`429`	Ошибка клиента	Слишком много запросов, превышен лимит
`500`	Ошибка сервера	Что-то сломалось на стороне сервиса

Запомнить просто: 2xx - успех, 4xx - вы что-то сделали не так, 5xx - сервис сам виноват.

Полный пример

Запрос - получить пользователя с номером 42:

GET /v1/users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer ВАШ_ТОКЕН
Accept: application/json

Ответ - код 200 и данные в JSON:

{
  "id": 42,
  "name": "Анна",
  "email": "anna@example.com",
  "active": true
}