Спроектировать REST API для интернет-магазина книг

REST API для интернет-магазина книг

Общие принципы проектирования

Базовый URL: https://api.bookstore.com/v1

Аутентификация: JWT токен в заголовке Authorization: Bearer {token}

Формат ответов: JSON

1. Эндпоинты работы с книгами

Получение списка всех книг

GET /books
Параметры:
- page (int): номер страницы (по умолчанию 1)
- limit (int): количество книг на странице (по умолчанию 20)
- sort (string): сортировка (price_asc, price_desc, title, rating)
- author (string): фильтр по автору
- search (string): полнотекстовый поиск

Ответ 200 OK:
{
  "data": [{"id": "uuid", "title": "Война и мир", "author": "Лев Толстой", "isbn": "978-5-17-070490-8", "price": 599.99, "stock": 45, "rating": 4.8}],
  "pagination": {"page": 1, "limit": 20, "total": 156}
}

Получение книги по ID

GET /books/{id}

Ответ 200 OK:
{
  "id": "uuid",
  "title": "Война и мир",
  "author": "Лев Толстой",
  "isbn": "978-5-17-070490-8",
  "price": 599.99,
  "stock": 45
}

Ответ 404 Not Found: {"error": "Book not found"}

Создание новой книги (администратор)

POST /books
Требуется: Authorization

Тело запроса:
{"title": "Война и мир", "author": "Лев Толстой", "isbn": "978-5-17-070490-8", "price": 599.99, "stock": 100}

Ответ 201 Created: {"id": "uuid", ...}
Ответ 400 Bad Request: {"error": "Invalid ISBN format"}
Ответ 409 Conflict: {"error": "Book with this ISBN already exists"}
Ответ 403 Forbidden: {"error": "Access denied"}

Обновление книги

PUT /books/{id}
Требуется: Authorization (администратор)

Тело запроса:
{"price": 699.99, "stock": 80}

Ответ 200 OK: {"id": "uuid", ...}
Ответ 404 Not Found
Ответ 403 Forbidden

Удаление книги

DELETE /books/{id}
Требуется: Authorization (администратор)

Ответ 204 No Content
Ответ 404 Not Found
Ответ 403 Forbidden

2. Эндпоинты работы с корзиной

Получение содержимого корзины

GET /cart
Требуется: Authorization

Ответ 200 OK:
{
  "id": "uuid",
  "items": [
    {"id": "uuid", "book_id": "uuid", "title": "Война и мир", "price": 599.99, "quantity": 2, "subtotal": 1199.98}
  ],
  "total": 1199.98,
  "currency": "RUB"
}

Добавление книги в корзину

POST /cart/items
Требуется: Authorization

Тело запроса:
{"book_id": "uuid", "quantity": 2}

Ответ 200 OK:
{"id": "uuid", "book_id": "uuid", "title": "Война и мир", "price": 599.99, "quantity": 2, "subtotal": 1199.98}

Ответ 400 Bad Request: {"error": "Quantity exceeds available stock", "available": 10}
Ответ 404 Not Found: {"error": "Book not found"}

Обновление количества в корзине

PUT /cart/items/{item_id}
Требуется: Authorization

Тело запроса:
{"quantity": 5}

Ответ 200 OK: {"id": "uuid", "quantity": 5, "subtotal": 2999.95}
Ответ 400 Bad Request: {"error": "Quantity exceeds available stock"}
Ответ 404 Not Found: {"error": "Item not found in cart"}

Удаление книги из корзины

DELETE /cart/items/{item_id}
Требуется: Authorization

Ответ 204 No Content
Ответ 404 Not Found

Очистка корзины

DELETE /cart
Требуется: Authorization

Ответ 204 No Content

3. Эндпоинты для оформления заказа

Создание заказа

POST /orders
Требуется: Authorization

Тело запроса:
{
  "shipping_address": {"street": "ул. Красная, 10", "city": "Москва", "postal_code": "123456", "country": "Россия"},
  "payment_method": "credit_card",
  "notes": "Оставить у двери"
}

Ответ 201 Created:
{
  "id": "uuid",
  "status": "pending",
  "items": [...],
  "total": 1529.98,
  "payment_status": "pending",
  "estimated_delivery": "2024-03-25"
}

Ответ 400 Bad Request: {"error": "Cart is empty"}
Ответ 400 Bad Request: {"error": "Invalid shipping address"}

Получение заказа по ID

GET /orders/{id}
Требуется: Authorization

Ответ 200 OK:
{"id": "uuid", "status": "shipped", "items": [...], "total": 1529.98, "payment_status": "completed", "tracking_number": "TRK123456789"}

Ответ 404 Not Found
Ответ 403 Forbidden: {"error": "You don't have access to this order"}

Получение списка заказов пользователя

GET /orders
Требуется: Authorization
Параметры:
- status: фильтр (pending, confirmed, shipped, delivered, cancelled)
- limit (по умолчанию 20)
- page (по умолчанию 1)

Ответ 200 OK: {"data": [...], "pagination": {...}}

Отмена заказа

POST /orders/{id}/cancel
Требуется: Authorization

Тело запроса:
{"reason": "Changed my mind"}

Ответ 200 OK:
{"id": "uuid", "status": "cancelled", "refund_amount": 1529.98, "refund_status": "processing"}

Ответ 400 Bad Request: {"error": "Order cannot be cancelled (already shipped)"}

4. Коды HTTP ответов

Основные принципы API

1. RESTful соглашения:

• Существительные вместо глаголов в URL
• HTTP методы соответствуют действиям (GET=чтение, POST=создание, PUT=обновление, DELETE=удаление)
• Версионирование в URL (/v1/)

2. Безопасность:

• JWT аутентификация для защиты
• Проверка прав доступа на уровне администратора
• Валидация всех входных данных
• HTTPS обязателен

3. Масштабируемость:

• Пагинация для списков
• Фильтрация и сортировка
• Кэширование возможных ответов
• Rate limiting для защиты от DDoS

4. Удобство:

• Понятные коды ошибок
• Полные описания ошибок в ответах
• Консистентная структура всех ответов
• Поддержка поиска и фильтрации

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