Принципы REST API

EMD Cloud API построен на принципах REST (Representational State Transfer) — архитектурного стиля для создания веб-сервисов.

Что такое REST?

REST — это подход к проектированию API, который использует стандартные HTTP методы для выполнения операций над ресурсами. Каждый ресурс (коллекция, запись, файл) имеет уникальный URL, а действия над ним выполняются с помощью HTTP методов.

HTTP методы

API использует стандартные HTTP методы для различных операций:

Метод	Назначение	Пример
GET	Получение данных	Получить список записей
POST	Создание ресурса	Создать новую запись
PUT	Полное обновление	Обновить всю запись
PATCH	Частичное обновление	Изменить отдельные поля
DELETE	Удаление ресурса	Удалить запись

Структура URL

URL в API EMD Cloud следует логической структуре:

https://api.emd.one/api/app/{app-id}/{resource}/{id}

Где:

• {app-id} — идентификатор вашего пространства
• {resource} — тип ресурса (database, users, storage и т.д.)
• {id} — идентификатор конкретного объекта (опционально)

Примеры URL

GET  /api/app/5f2da2f9/database        # Получить список коллекций
POST /api/app/5f2da2f9/database        # Создать коллекцию
GET  /api/app/5f2da2f9/database/users  # Получить записи из коллекции users
PUT  /api/app/5f2da2f9/database/users/123  # Обновить запись с ID 123

Формат данных

JSON

Все запросы и ответы используют формат JSON. При отправке данных необходимо указывать заголовок:

Content-Type: application/json

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

POST /api/app/5f2da2f9/database/users
Content-Type: application/json

{
  "name": "Иван Петров",
  "email": "ivan@example.com",
  "age": 30
}

Пример ответа

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Иван Петров",
  "email": "ivan@example.com",
  "age": 30,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

HTTP коды ответов

API использует стандартные HTTP коды для индикации результата операции:

Успешные ответы (2xx)

Код	Значение	Когда используется
200 OK	Успешно	GET, PUT, PATCH запросы
201 Created	Создано	POST запросы
204 No Content	Нет содержимого	DELETE запросы

Ошибки клиента (4xx)

Код	Значение	Причина
400 Bad Request	Неверный запрос	Ошибка в данных запроса
401 Unauthorized	Не авторизован	Отсутствует или невалидный токен
403 Forbidden	Доступ запрещён	Недостаточно прав
404 Not Found	Не найдено	Ресурс не существует
422 Unprocessable Entity	Невалидные данные	Ошибка валидации

Ошибки сервера (5xx)

Код	Значение	Причина
500 Internal Server Error	Внутренняя ошибка	Ошибка на сервере
503 Service Unavailable	Сервис недоступен	Технические работы

Формат ошибок

При возникновении ошибки API возвращает объект с описанием:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Поле email обязательно для заполнения",
    "details": {
      "field": "email",
      "reason": "required"
    }
  }
}

Аутентификация

Для доступа к API необходимо передавать JWT токен в заголовке:

Authorization: Bearer YOUR_JWT_TOKEN

Подробнее об получении токена читайте в разделе Авторизация.

Пагинация

Для методов, возвращающих списки, поддерживается пагинация через параметры:

GET /api/app/5f2da2f9/database/users?limit=20&offset=0

Параметры:

• limit — количество записей на странице (по умолчанию 50, максимум 100)
• offset — смещение от начала списка

Ответ включает метаданные о пагинации:

{
  "data": [...],
  "meta": {
    "total": 150,
    "limit": 20,
    "offset": 0
  }
}

Фильтрация и сортировка

API поддерживает фильтрацию и сортировку данных через параметры запроса:

GET /api/app/5f2da2f9/database/users?filter[age][$gte]=18&sort=-createdAt

Подробности о синтаксисе фильтров смотрите в интерактивной документации вашего пространства.

Что дальше?

• Обзор методов — изучите доступные группы методов
• Примеры использования — посмотрите практические примеры
• Интерактивная документация — протестируйте API в браузере