REST • JSON • S3 • Database

Документация по работе с REST API

Ниже пример страницы в формате технического мануала. Она показывает базовый цикл работы с API: аутентификация, загрузка файла в S3 через backend, получение данных из базы и разбор типовых ответов.

Протокол HTTPS / JSON
Авторизация Bearer Token
Основные кейсы Upload / Read / Filter

1. Авторизация

Перед выполнением запросов клиент получает access token и передаёт его в заголовке Authorization.

POST /auth/token

Описание

Возвращает токен доступа для дальнейшей работы с защищёнными эндпоинтами.

application/json public endpoint

Пример запроса

{
  "client_id": "demo-client",
  "client_secret": "demo-secret"
}

cURL

curl -X POST "https://api.example.com/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "demo-client",
    "client_secret": "demo-secret"
  }'

Ответ

{
  "access_token": "eyJhbGciOiJI...",
  "token_type": "Bearer",
  "expires_in": 3600
}

2. Загрузка файла в S3

API принимает файл, валидирует его и сохраняет объект в S3‑совместимое хранилище.

POST /files/upload

Описание

Загружает файл в bucket и возвращает идентификатор, путь и публичный или внутренний URL.

  • Поддержка multipart/form-data
  • Сервер может назначать уникальный ключ объекта
  • Метаданные сохраняются в БД
Headers Authorization: Bearer <token>
Body file, folder, is_public
Content-Type multipart/form-data
Response 201 Created

cURL

curl -X POST "https://api.example.com/v1/files/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@./report.pdf" \
  -F "folder=docs/2026/04" \
  -F "is_public=false"

Успешный ответ

{
  "success": true,
  "data": {
    "file_id": "f_01HS82D9M0",
    "file_name": "report.pdf",
    "mime_type": "application/pdf",
    "size": 284193,
    "bucket": "project-files",
    "object_key": "docs/2026/04/1745312231_report.pdf",
    "url": "https://cdn.example.com/docs/2026/04/1745312231_report.pdf",
    "created_at": "2026-04-22T11:32:08Z"
  }
}
После загрузки backend обычно записывает метаданные файла в БД: имя, размер, bucket, object_key, user_id, created_at.

3. Получение данных из базы через API

Клиент не обращается к БД напрямую. Он вызывает REST‑эндпоинт, а backend уже читает таблицы, применяет фильтры и отдаёт JSON.

GET /users?limit=20&offset=0&status=active

Описание

Возвращает список пользователей из БД с пагинацией и фильтрацией по статусу.

  • limit — размер страницы
  • offset — смещение
  • status — фильтр по состоянию записи

Пример SQL на backend

SELECT id, name, email, status, created_at
FROM users
WHERE status = 'active'
ORDER BY id DESC
LIMIT 20 OFFSET 0;

cURL

curl -X GET "https://api.example.com/v1/users?limit=20&offset=0&status=active" \
  -H "Authorization: Bearer YOUR_TOKEN"

Ответ

{
  "success": true,
  "meta": {
    "limit": 20,
    "offset": 0,
    "total": 245
  },
  "data": [
    {
      "id": 125,
      "name": "Ivan Petrov",
      "email": "ivan.petrov@example.com",
      "status": "active",
      "created_at": "2026-04-20T08:14:11Z"
    },
    {
      "id": 124,
      "name": "Anna Sokolova",
      "email": "anna.sokolova@example.com",
      "status": "active",
      "created_at": "2026-04-19T15:42:09Z"
    }
  ]
}
Не отдавайте клиенту сырой SQL и внутреннюю структуру БД. REST API должен возвращать только необходимые поля и безопасные данные.

4. Статусы и ошибки

Единый формат ошибок упрощает интеграцию и диагностику проблем на стороне клиента.

HTTP статус Когда используется Пример
200 OK Успешный запрос на чтение Получение списка пользователей
201 Created Успешное создание ресурса Загрузка файла в S3
400 Bad Request Некорректные параметры Отсутствует обязательное поле
401 Unauthorized Нет токена или токен невалиден Неверный Bearer token
404 Not Found Ресурс не найден Файл или пользователь отсутствует
500 Internal Server Error Ошибка сервера Сбой при работе с БД или S3

Единый формат ошибки

{
  "success": false,
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "Maximum allowed file size is 10 MB"
  }
}

5. Общий сценарий работы

Пример последовательности действий для типового клиента.

1. POST /auth/token
2. Получить access_token
3. POST /files/upload — отправить файл в S3 через API
4. GET /users — получить данные из БД
5. Обработать success / error в ответе

Рекомендуемая структура backend-логики

Controller -> Service -> Repository -> DB / S3

Что полезно добавить в реальный проект

  • Swagger / OpenAPI спецификацию
  • JWT refresh tokens
  • Rate limiting
  • Idempotency для upload/POST операций
  • Логирование request_id и audit trail
(c)fkorr.com