8 минутПредставьте интернет как ресторан: вы хотите получить блюдо (данные), но вы не можете просто зайти на кухню (сервер) и начать готовить самостоятельно. Вам нужен «официант» — API, который передаст ваш запрос серверу и вернет результат. REST — это язык, на котором «общаются» клиент и сервер. В статье разберем, как устроены эти запросы и какие методы используются для обмена данными.
Что такое REST API-запрос: простое объяснение взаимодействия «клиент–сервер»
REST (Representational State Transfer) — это не жесткий закон, а скорее архитектурный стиль, набор рекомендаций о том, как программам обмениваться информацией. Самая простая аналогия — окошко выдачи в банке или на почте.
Клиент ― это ваш браузер, мобильное приложение или другая программа. Клиент всегда инициатор — он чего-то хочет.
Сервер ― это компьютер где-то в дата-центре, который хранит базу данных и логику. Он отвечает на запросы.
Запрос ― это само обращение. Клиент отправляет «конверт» с инструкциями.
Ответ ― реакция сервера. Он присылает данные или сообщает об ошибке.
Основные HTTP-методы в REST API
В общении люди используют глаголы, чтобы объяснить действие. В HTTP-протоколе, на котором работает REST, тоже есть свои «глаголы». Их называют методами. Они говорят серверу, что именно мы хотим сделать с ресурсом (данными).
Представьте, что мы управляем списком контактов в телефоне. Вот как методы соответствуют нашим действиям:
Метод REST API GET (получить) ― самый безопасный метод. Мы ничего не меняем, просто смотрим. Например: «Покажи мне номер телефона Ивана». Используется, когда нужно скачать данные, открыть страницу, получить список товаров.
Метод REST API POST (создать) ― отправляет данные, чтобы сервер создал новую запись. Например: «Добавь новый контакт: Анна, 8-900-123-45-67». Используется при регистрации, оформлении заказа, публикации комментария.
Метод REST API PUT (заменить целиком) ― метод полного обновления. Старую запись полностью заменяют новой. Пример PUT-запроса: «Вот новая карточка для Анны. Старую версию замени этой». Если вы не укажете в новой версии фамилию, которая была в старой, она пропадет. Используется для полного редактирования профиля или товара.
Метод REST API PATCH (изменить частично) ― более аккуратный метод обновления. Например, «У Анны изменился только email, поменяй только это поле, остальное не трогай». Используется при смене пароля, изменении статуса заказа.
Структура REST API-запроса с примерами
Чтобы сервер понял нас правильно, запрос должен быть оформлен по стандарту. Он состоит из нескольких частей, как официальное письмо.
Endpoint запроса (конечная точка). Это адрес, куда мы обращаемся. Выглядит как обычная ссылка (URL).
Метод — тот самый «глагол» (GET, POST и т. д.), о котором мы говорили выше.
Headers (заголовки) — служебная информация, метаданные. Это как марки и штампы на конверте. Здесь указывается формат данных (например, JSON), секретный ключ (токен), подтверждающий право доступа, и информацию о клиенте (браузере или приложении).
Body (тело запроса) ―полезная нагрузка. Это данные, которые мы передаем серверу. У метода GET тела обычно нет (мы только запрашиваем информацию). У POST или PUT в теле содержатся данные, например: имя пользователя, пароль, состав заказа.
Рассмотрим пример запроса с методом POST:
POST /api/orders/create HTTP/1.1
Host: myshop.com
Content-Type: application/json
{
"product_id": 55,
"quantity": 2,
"comment": "Позвонить перед доставкой"
}
Где POST — мы просим создать новую запись.
/api/orders/create — мы обращаемся в раздел создания заказов.
JSON внизу — это тело запроса. Мы указали, что хотим купить товар номер 55 в количестве двух штук и оставили комментарий.
В ответ сервер пришлет статус-код. Если все хорошо, это будет 200 OK или 201 Created. Если мы ошиблись в данных — 400 Bad Request, а если забыли токен доступа — 401 Unauthorized.
Пример GET-запроса:
GET /api/orders/123 HTTP/1.1
Host: myshop.com
GET — мы просим сервер вернуть данные, не изменяя их.
/api/orders/123 — обращаемся к заказу с ID 123.
В ответ сервер пришлет статус-код и данные заказа в формате JSON. Примеры:
200 OK — заказ найден, данные возвращены.
404 Not Found — заказ с таким ID не существует.
JSON-ответ может выглядеть так:
{
"order_id": 123,
"product_id": 55,
"quantity": 2,
"status": "confirmed"
}
Структура ответа REST API
Сервер получил ваш запрос, обработал его и отправил ответ. Ответ тоже имеет строгую структуру.
Сначала идет Status Code (код состояния). Это трехзначное число, которое сразу показывает результат запроса. Их нужно знать хотя бы по группам:
2xx (успех): запрос выполнен успешно. Примеры:
- 200 OK (все прошло хорошо),
- 201 Created (ресурс успешно создан).
3xx (перенаправление): ресурс находится по другому адресу.
4xx (ошибка клиента):проблема в запросе. Примеры:
- 400 Bad Request — некорректные данные от клиента,
- 404 Not Found — ресурс не найден.
5xx (ошибка сервера): проблема на сервере.
- 500 Internal Server Error — внутренняя ошибка сервера.
Как разбирать ошибки 400 или 500?
Ошибка 400 говорит, что данные клиента некорректны. Обязательно смотрите текст в теле ответа, там часто указана конкретная причина. Например, «не указан email».
Код 500 означает сбой на сервере. В этом случае стоит проверить корректность своих данных и попробовать повторить запрос позже.
Headers (заголовках) содержат служебную информацию: тип данных, правила кеширования и другие параметры.
Body (тело ответа) содержит сам результат запроса. Например, список пользователей или подтверждение действия — «Заказ успешно создан».
Форматы данных в REST API
Раньше программы общались с помощью XML. Это громоздкий формат, похожий на HTML, с множеством угловых скобок. Читать его вручную трудно,и он занимает много места.
Сегодня золотым стандартом REST стал JSON (JavaScript Object Notation). Формат представляет собой набор пар «ключ: значение». Он легко читается как людьми, так и машинами.
Пример JSON:
{
"id": 1,
"name": "Алексей",
"isAdmin": true
}
Есть альтернативные форматы:
XML все еще встречается в старых банковских системах и государственном ПО (SOAP-архитектурах), но в новых REST-проектах почти не используется.
YAML чаще используется для конфигурационных файлов, а не для передачи данных.
Protobuf ― бинарный формат от Google. Используется там, где важна сверхвысокая скорость и экономия трафика (например, в микросервисах).
Параметры запросов REST API на понятных примерах
Path Parameters (параметры пути) ― это часть самого адреса ресурса. Используются, чтобы указать конкретный объект.
Пример:
GET /users/50
Здесь 50 — это ID конкретного пользователя. Мы говорим: «Дай мне пользователя с номером 50». Это неотъемлемая часть URL-адреса.
Query Parameters (строка запроса) ― это фильтры и настройки отображения. Идут в конце ссылки после знака вопроса ? и разделяются амперсандом &.
Пример:
GET /users?role=admin&sort=age
Мы говорим: «Дай мне пользователей, НО только админов И отсортируй их по возрасту». Если убрать эту часть, запрос все равно сработает, просто вернет весь список без фильтрации.
Body Parameters (параметры в теле запроса) — используются для передачи сложных или объемных данных, которые не показываются в адресной строке (например, пароли или длинные тексты).
Например, при регистрации вы отправляете JSON с логином и паролем внутри тела запроса POST. В адресной строке эти данные не видны:
{
"username": "ivan123",
"password": "secretPassword"
}
Как читать документацию REST API
Чтобы работать с чужим API, нужно внимательно читать инструкцию. Обычно она представлена в формате Swagger (OpenAPI) или просто текстом. На что обращать внимание в первую очередь:
Base URL: основной адрес сервера. Все запросы будут отправляться сюда.
Authentication: как авторизоваться в системе? Нужен ли API-ключ в заголовке или логин/пароль или другой способ?
Endpoints: список доступных путей и ресурсов.
Required parameters: обязательные поля. Если их не передать, сервер вернет ошибку 400.
Example Request/Response: примеры того, что отправить и какой ответ вернется. Это самая полезная часть для копирования и адаптации под свои нужды.
Примеры запросов для REST API взаимодействия
Предположим, мы работаем с API книжного магазина. Ресурс — /books.
1. Получить список всех книг (GET)
Запрос:
GET /books
Host: api.bookstore.com
Ответ (200 OK):
[
{"id": 1, "title": "Война и мир"},
{"id": 2, "title": "Гарри Поттер"}
]
2. Добавить новую книгу (POST)
Запрос:
POST /books
Content-Type: application/json
{
"title": "Властелин Колец",
}
Ответ (201 Created):
{
"id": 3,
"status": "success"
}
3. Исправить опечатку в названии (PATCH)
Запрос (обратите внимание, что ID книги указывается в пути — /books/3):
PATCH /books/3
Content-Type: application/json
Тело запроса:
{
"title": "Властелин Колец: Братство Кольца"
}
4. Удалить книгу (DELETE)
Запрос:
DELETE /books/3
Ответ (204 No Content): пустое тело, сервер просто подтверждает, что удаление прошло успешно.
Типичные ошибки при работе с REST API
Даже опытные разработчики иногда сталкиваются с проблемами:
Использование неправильных методов. GET для удаления данных или POST для получения — плохая практика и нарушение безопасности.
Забытый заголовок Content-Type. Если вы отправляете JSON, но не указываете Content-Type: application/json, сервер может не понять ваш «язык» и выдать ошибку.
Игнорирование статус-кодов. Нельзя ориентироваться только на тело ответа. Всегда проверяйте код: если там 401, значит токен доступа недействителен, а не «база данных пуста».
Секретные данные в URL. Никогда не передавайте пароли или токены через Query-параметры (?password=123). Ссылки сохраняются в истории браузера и логах серверов, и их может увидеть кто угодно.
Ответы на частые вопросы новичков
Как передавать query-параметры?
Они добавляются в конец ссылки после знака вопроса и записываются в формате «ключ=значение». Если параметров несколько, их разделяют символом амперсанда (&). Например, ссылка с фильтрами будет выглядеть так: url?color=red&size=42.
Как формировать body JSON?
Используйте фигурные скобки, а названия полей и все строковые значения обязательно заключайте в двойные кавычки. Пары «ключ: значение» перечисляются через запятую, но после последнего элемента запятая не ставится. JSON — строгий текстовый формат, поэтому важно соблюдать синтаксис.
Как анализировать статус-коды?
Смотрите на первую цифру: 2xx означает успешное выполнение, а 4xx — ошибку на стороне клиента (например, опечатку или отсутствие доступа). Если вы видите 5xx, проблема возникла на стороне сервера, и, скорее всего, запрос был сформирован корректно. Это основной ориентир для поиска причины сбоя.
Как отправлять запросы в Postman?
Выберите нужный метод (GET, POST и т. д.) в выпадающем списке и вставьте адрес ссылки в соседнее поле. Если нужно передать данные, добавьте их на вкладке Body, выбрав формат JSON. Нажмите синюю кнопку Send, и в нижней части экрана отобразится ответ.
Как выбрать HTTP-метод?
Отталкивайтесь от цели запроса: для получения данных используйте GET, а для создания новых записей — POST. Если нужно изменить существующую информацию, применяйте PUT или PATCH. Для удаления всегда используют метод DELETE.
Как передавать данные через path?
Path-параметры встраиваются непосредственно в адрес запроса и указывают на конкретный ресурс, например ID пользователя. В документации их часто обозначают как /users/:id), а в реальном запросе подставляют значение — например, /users/50.
Как обрабатывать ответ сервера?
Сначала всегда проверяйте статус-код: если он успешный (например, 200 OK), можно приступать к разбору содержимого. Затем преобразуйте полученный JSON-ответ в объект или массив вашего языка программирования (парсинг). Только после этого извлекайте нужные данные для работы.
Как тестировать PUT и DELETE?
Не стоит тренироваться на реальных важных данных, чтобы случайно их не удалить. Безопаснее сначала создать тестовую запись через POST и получить ее ID, а затем применять методы изменения или удаления именно к этому объекту.
