Практический курс по REST API: реальные сценарии интеграции

Основы REST на примере E-commerce: CRUD-операции с товарами и заказами

Архитектурный стиль REST (Representational State Transfer) стал стандартом де-факто для построения веб-сервисов. Чтобы понять его принципы, лучше всего рассмотреть работу интернет-магазина. В любой E-commerce системе ключевыми сущностями являются Товары (Products) и Заказы (Orders). В терминологии REST эти сущности называются ресурсами.

Взаимодействие с ресурсами строится вокруг четырех базовых действий, известных под аббревиатурой CRUD: Create (Создать), Read (Прочитать), Update (Обновить), Delete (Удалить). REST связывает эти действия с методами протокола HTTP.

!Связь CRUD-операций и методов HTTP

Ресурсы и их идентификация (URI)

В REST API каждый ресурс должен иметь уникальный адрес — URI (Uniform Resource Identifier). Хорошей практикой считается использование существительных во множественном числе для именования путей.

Для нашего интернет-магазина базовые маршруты будут выглядеть так:

* /products — коллекция всех товаров. * /products/123 — конкретный товар с ID 123. * /orders — коллекция всех заказов. * /orders/456 — конкретный заказ с ID 456.

Использование глаголов в URL (например, /getProducts или /createOrder) является антипаттерном в REST. Действие определяется не URL, а HTTP-методом.

Получение данных: метод GET

Метод GET используется для чтения информации. Это безопасный метод: он не изменяет состояние сервера. Сколько бы раз вы ни вызвали GET-запрос, данные в базе магазина останутся прежними.

Получение списка товаров

Запрос клиента:

Сервер возвращает список товаров в формате JSON и статус код 200 OK.

В реальных сценариях список товаров редко запрашивают целиком. Для фильтрации, сортировки и пагинации используются query parameters (параметры строки запроса):

GET /products?category=electronics&sort=price_asc&limit=10

Получение одного товара

Чтобы получить детальную информацию о конкретном товаре (например, для карточки товара), клиент обращается к ресурсу по его уникальному идентификатору:

GET /products/42

Если товар существует, сервер вернет JSON-объект товара. Если товара с таким ID нет, сервер обязан вернуть статус 404 Not Found.

Создание данных: метод POST

Для добавления новых ресурсов используется метод POST. В отличие от GET, этот метод изменяет состояние сервера и не является идемпотентным (повторная отправка того же запроса создаст дубликат ресурса, если сервер не защищен от этого логически).

Пример: Оформление заказа

Клиент отправляет JSON с составом корзины на сервер.

Запрос:

При успешном создании заказа сервер должен вернуть статус 201 Created. Также хорошим тоном считается добавление заголовка Location, указывающего на URL только что созданного ресурса:

Location: /api/v1/orders/999

Обновление данных: PUT и PATCH

В REST существует два способа изменить ресурс. Различие между ними критически важно для правильной интеграции.

PUT: Полная замена

Метод PUT подразумевает, что клиент отправляет полное обновленное представление ресурса. Если вы хотите изменить только цену товара, но используете PUT, вы обязаны передать и название, и описание, и категорию. Если вы передадите только цену, остальные поля могут быть затерты (обнулены), так как PUT полностью перезаписывает ресурс по указанному адресу.

Пример запроса (обновляем товар целиком):

PATCH: Частичное обновление

Метод PATCH используется для точечных изменений. Это наиболее частый сценарий в E-commerce, например, когда нужно изменить статус заказа или обновить остаток на складе.

Пример запроса (меняем только цену):

Сервер примет этот JSON, найдет товар с ID 42 и обновит только поле price, оставив остальные данные без изменений.

Удаление данных: метод DELETE

Метод DELETE удаляет указанный ресурс.

DELETE /products/42

При успешном удалении сервер обычно возвращает статус 204 No Content (операция успешна, тела ответа нет) или 200 OK с мета-информацией.

В реальных E-commerce системах часто используется Soft Delete (мягкое удаление). Вместо физического стирания записи из базы данных, товару проставляется флаг is_deleted: true или active: false. Для клиента API это выглядит как удаление (при попытке сделать GET по этому ID вернется 404), но данные сохраняются для истории и аналитики.

Вложенные ресурсы

Часто ресурсы логически связаны. Например, у конкретного заказа есть позиции (товарные строки). В REST это можно реализовать через вложенные пути:

GET /orders/999/items

Этот запрос вернет список товаров, входящих именно в заказ №999. Это позволяет структурировать API логично и предсказуемо.

Итоги

* Ресурсы и URI: В REST мы работаем с существительными (Products, Orders). URL указывает на ресурс, а не на действие. * HTTP Методы: Действие определяется методом: GET (чтение), POST (создание), PUT (полная замена), PATCH (частичное обновление), DELETE (удаление). * Статус коды: Ответ сервера должен содержать правильный статус код (200, 201, 204, 404), сообщающий о результате операции. * Безопасность методов: GET-запросы не должны менять данные на сервере.

FinTech интеграции: подключение платежного шлюза, безопасность и JWT-авторизация

Финансовые технологии (FinTech) предъявляют к API значительно более строгие требования, чем обычные E-commerce проекты. Если в каталоге товаров ошибка приведет к неверному описанию, то в платежной системе ошибка может стоить денег, репутации и юридических проблем. В этой статье мы разберем архитектурные паттерны, необходимые для безопасной обработки платежей и авторизации.

Архитектура платежного шлюза

В современной веб-разработке магазины редко обрабатывают данные банковских карт напрямую. Это связано со стандартом безопасности PCI DSS (Payment Card Industry Data Security Standard). Чтобы соответствовать ему, используется паттерн Tokenization (Токенизация).

Процесс оплаты выглядит следующим образом:

!Поток данных при безопасной оплате через токенизацию

Такой подход гарантирует, что «сырые» данные карт никогда не касаются ваших серверов, снимая с вас огромный пласт ответственности за безопасность данных.

Идемпотентность запросов

В финансовых API критически важно понятие идемпотентности. Представьте ситуацию: клиент нажимает кнопку «Оплатить», ваш сервер отправляет запрос в банк, банк списывает деньги, но ответ от банка теряется из-за сбоя сети. Клиент видит ошибку и нажимает «Оплатить» снова. Без защиты деньги спишутся дважды.

Идемпотентность — это свойство операции, при котором повторное выполнение действия приводит к тому же результату, что и первое, без побочных эффектов.

Математически это записывается так:

Где — это функция (операция API), а — входные данные. Это означает, что применение функции к результату её же выполнения (или повторный вызов с теми же аргументами) не меняет состояние системы по сравнению с однократным вызовом.

Реализация через Idempotency-Key

В REST API для обеспечения идемпотентности используется специальный заголовок Idempotency-Key. Это уникальная строка (обычно UUID), которую генерирует клиент перед запросом.

Пример запроса на создание платежа:

Логика сервера при получении такого заголовка:

Это гарантирует, что даже при 10 повторных нажатиях кнопки списание произойдет ровно один раз.

JWT-авторизация (JSON Web Token)

В отличие от классических сессий, где сервер хранит состояние пользователя в памяти или базе данных, REST API стремится к Stateless (отсутствию состояния). Стандартом для передачи данных аутентификации стал JWT.

JWT — это строка, состоящая из трех частей, разделенных точкой: Header.Payload.Signature.

1. Header (Заголовок)

2. Payload (Полезная нагрузка)

3. Signature (Подпись)

Где: * — итоговая подпись (Signature). * — алгоритм хеширования с использованием секретного ключа. * — секретный ключ (Secret Key), который хранится только на сервере. * — закодированный в Base64Url заголовок. * — закодированная в Base64Url полезная нагрузка. * — операция конкатенации (склеивания) строк.

!Формирование цифровой подписи JWT

Когда клиент присылает токен, сервер берет Header и Payload из токена, снова хеширует их своим секретным ключом и сверяет полученную подпись с той, что пришла в токене. Если хоть один символ в Payload был изменен (например, role: user заменено на role: admin), подписи не совпадут, и сервер отвергнет запрос.

Безопасность Webhooks (Обратных вызовов)

Платежи часто проходят асинхронно. Вы отправили запрос, а реальное списание произошло через 10 секунд или даже минут. Платежный шлюз уведомляет ваш сервер об успехе через Webhook — POST-запрос на ваш специальный URL.

Злоумышленник может попытаться подделать такой запрос, отправив вам фальшивое уведомление «Платеж прошел успешно», чтобы получить товар бесплатно. Для защиты используется проверка подписи (Webhook Signature).

Провайдер подписывает тело запроса своим секретным ключом и передает подпись в заголовке (например, X-Signature). Ваш сервер должен самостоятельно вычислить хеш от полученного тела запроса и сравнить его с заголовком.

Пример проверки на Node.js (псевдокод):

Итоги

* Токенизация: Никогда не обрабатывайте данные карт на своем бэкенде. Используйте временные токены от провайдера. * Идемпотентность: Используйте заголовок Idempotency-Key для защиты от дублирования транзакций при сетевых сбоях. * JWT: Обеспечивает Stateless-авторизацию. Безопасность гарантируется цифровой подписью, которая валидируется на сервере. * Валидация Webhooks: Всегда проверяйте криптографическую подпись входящих уведомлений от платежных систем, чтобы избежать мошенничества.