Ресурсы, адреса и HTTP-методы
В REST-подходе данные представляют как ресурсы: например, пользователи, заказы или сообщения. Каждый ресурс обычно доступен по определённому URL. Действие задаётся HTTP-методом. GET применяют для чтения, POST — для создания или запуска операции, PUT и PATCH — для изменения, DELETE — для удаления. Важно не запоминать методы как магические команды, а понимать их назначение. Клиентский модуль должен формировать запрос так, чтобы адрес, метод и данные соответствовали смыслу операции. Это упрощает чтение кода и снижает вероятность случайно отправить изменение вместо безопасного запроса на получение данных.
Параметры, тело запроса и заголовки
У запроса есть несколько каналов передачи информации. Параметры пути обычно идентифицируют конкретный ресурс, параметры строки запроса уточняют выборку, например фильтр или номер страницы, а тело содержит более объёмные данные для создания и изменения. Заголовки передают служебную информацию: формат данных, язык, идентификатор авторизации и другие настройки протокола. В модуле API полезно явно разделять эти части. Тогда функция не превращается в нечитабельную строку, собранную вручную из фрагментов, а параметры можно проверять до отправки.
Коды ответа и обработка ошибок
Сетевой запрос может завершиться технически успешно, но вернуть прикладную ошибку. Поэтому модуль должен проверять не только факт получения ответа, но и его статус. Коды группы 2xx обычно означают успешное выполнение, 4xx указывают на проблему с запросом или доступом, а 5xx — на ошибку на стороне сервера. Полезно преобразовывать разные ошибки в единый формат приложения: код, понятное сообщение и при необходимости исходные детали. При этом чувствительные данные, например токены, не должны попадать в пользовательские сообщения или обычные журналы.
Как организовать модуль API в проекте
Хороший модуль инкапсулирует сетевую часть. В одном месте задаются базовый адрес, общие заголовки, тайм-аут и правила авторизации. Поверх базового клиента создаются функции вроде getUser, createOrder или updateProfile. Эти функции принимают обычные данные приложения и возвращают уже разобранный результат. Такой подход уменьшает дублирование и позволяет заменить библиотеку запросов без переписывания бизнес-логики. Для устойчивости также важно предусмотреть тайм-ауты, отмену запросов и повторные попытки только там, где повтор не создаёт нежелательных дублей.
Попробуйте на практике
Спроектировать небольшой REST API-модуль для условного списка задач.
- Определите три операции: получить список задач, создать задачу и отметить задачу выполненной.
- Для каждой операции запишите HTTP-метод, адрес ресурса и где будут передаваться данные.
- Опишите единый формат успешного результата и ошибки, который будет использовать приложение.
- Выделите общие настройки клиента: базовый URL, формат данных, тайм-аут и место подключения авторизации.
- Проверьте, что бизнес-логике не нужно самостоятельно собирать URL или разбирать сетевые ошибки.
Как проверить результат. Схема считается удачной, если каждая операция имеет понятный метод и адрес, сетевые детали сосредоточены в одном модуле, а вызывающий код получает единообразный результат.
Частые вопросы
REST API обязательно использует JSON?
Нет. REST не требует конкретного формата данных. JSON распространён благодаря удобству, но технически API может использовать и другие форматы, если клиент и сервер договорились о них.
Чем PUT отличается от PATCH?
PUT обычно применяют для полной замены представления ресурса, а PATCH — для частичного изменения. Реальное поведение всё равно определяется конкретным API, поэтому нужно смотреть его контракт.
Нужно ли повторять запрос после любой ошибки?
Нет. Повтор оправдан только для временных сбоев и операций, где он безопасен. Например, бездумный повтор создания объекта может привести к дублям, если API не предусматривает защиту от этого.
Самостоятельный разбор темы. Содержание конкретной обучающей программы здесь не представлено.