Какой есть подход в RESTful API помимо CRUD?

Альтернативы CRUD в RESTful API: переход к resource-oriented и hypermedia дизайну

Классический CRUD (Create, Read, Update, Delete), отображаемый на HTTP-методы POST, GET, PUT/PATCH, DELETE, — это базовый, но часто недостаточный подход для сложных бизнес-, логик. Помимо него существуют более выразительные и гибкие паттерны, которые лучше отражают предметную область и улучшают семантическую ясность API.

Основные альтернативные подходы

1. Resource-Oriented Actions (Действия над ресурсами)

Вместо прямого отображения CRUD на ресурсы, мы моделируем специфичные действия как подресурсы или отдельные конечные точки. Это делает API более интуитивным и соответствующим бизнес-языку.

Пример: Система заказов

// Вместо PATCH /orders/{id} с телом {"status": "shipped"}
// Создаем явное действие:
POST /orders/{id}/ship
POST /orders/{id}/cancel
POST /orders/{id}/refund

// Или даже как подресурс:
POST /orders/{id}/actions/ship

Преимущества:

• Явная семантика: URL и метод HTTP четко описывают операцию.
• Безопасность: Легче применять контроль доступа к конкретным действиям.
• Атомарность: Действие может инкапсулировать сложную логику (обновление статуса, отправку уведомления, списание со склада).

2. Команды и события (CQRS-инспирированный подход)

Для сложных систем эффективно разделять операции на команды (запись) и запросы (чтение). В API это может отражаться через разные ресурсы или форматы.

// Команда на создание заказа (возвращает ID, но не данные)
POST /order-commands
Content-Type: application/json
{
    "type": "CreateOrder",
    "payload": {
        "items": [...],
        "userId": 123
    }
}
// Ответ: 202 Accepted с Location: /order-status/queue-id-456

// Отдельный ресурс для запроса данных заказа
GET /order-views/{id} // Возвращает DTO, оптимизированный для чтения

3. Hypermedia API (HATEOAS)

Это высшая форма REST, где API динамически направляет клиента через ссылки (links), встроенные в ответы. CRUD-операции становятся лишь частью навигации по графу состояний системы.

{
    "order": {
        "id": 123,
        "status": "pending",
        "total": 100.00,
        "_links": {
            "self": { "href": "/orders/123" },
            "cancel": { "href": "/orders/123/cancel", "method": "POST" },
            "pay": { "href": "/orders/123/payments", "method": "POST" }
        }
    }
}

Клиент не хардкодит URL, а следует по ссылкам, которые сервер предоставляет в зависимости от текущего состояния ресурса (например, ссылка cancel исчезает после отгрузки).

4. Статусные операции (Long-Running Processes)

Для асинхронных или долгих задач (генерация отчета, обработка видео) CRUD не подходит. Используется паттерн ресурс-задача (task resource).

// 1. Запуск задачи
POST /report-generations
{ "type": "annual_sales", "year": 2023 }
// Ответ: 202 Accepted с заголовком Location: /report-generations/789

// 2. Мониторинг статуса
GET /report-generations/789
{
    "id": 789,
    "status": "processing",
    "progress": 65,
    "resultUrl": null
}

// 3. Получение результата после завершения
GET /report-generations/789
{
    "status": "completed",
    "resultUrl": "/reports/file-2023-sales.pdf",
    "_links": { "download": { "href": "/reports/file-2023-sales.pdf" } }
}

5. Поиск и вычисления как ресурсы

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

// Ресурс "результат поиска"
POST /product-searches // Используем POST, т.к. запрос сложный и может быть длинным
{
    "filters": { "category": "books", "price": { "lt": 50 } },
    "sort": "rating"
}
// Ответ: 200 OK с телом — списком продуктов и метаданными поиска

// Ресурс "аналитика"
GET /sales-analytics?from=2024-01&to=2024-03&groupBy=month
// Возвращает вычисленные агрегаты, не изменяя состояние системы.

Критерии выбора подхода

• Сложность доменной логики: Если операции — простые изменения полей, CRUD может хватить. Если есть специфичные бизнес-процессы (отпуск, одобрение, расчёт) — используйте resource-oriented actions.
• Требования к клиентской сложности: Hypermedia уменьшает связанность, но требует от клиентов умения работать со ссылками.
• Производительность и масштабируемость: Для тяжелых операций или асинхронных процессов используйте статусные операции (task resources).
• Семантическая корректность HTTP: Всегда задавайтесь вопросом, является ли операция идемпотентной (используйте PUT) или неидемпотентной (используйте POST). Например, POST /orders/{id}/cancel семантически точнее, чем PUT /orders/{id} с полем статуса.

Заключение

Отход от чистого CRUD к более декларативным и ресурсно-ориентированным моделям позволяет создавать API, которые:

1. Лучше отражают предметную область бизнеса.
2. Упрощают клиентский код за счёт явной семантики.
3. Повышают устойчивость к изменениям (особенно с HATEOAS).
4. Обеспечивают корректное использование HTTP-протокола.

Ключ — в моделировании ресурсов как объектов предметной области с поведением, а не просто как строк таблиц базы данных. Это мышление переводит API из уровня простого "геттера/сеттера" данных в уровень управления бизнес- процессами и состояниями системы.