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

Почти все веб-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
}

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

В ответ сервис присылает данные (обычно 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
}