Перейти к основному содержимому

Интерактивная документация

EMD Cloud предоставляет интерактивную документацию API для каждого пространства, которая позволяет изучать методы и тестировать запросы прямо в браузере.

Где найти документацию?​

Документация API доступна для каждого вашего пространства (проекта) по адресу:

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

Где {app-id} — это идентификатор вашего пространства.

Как узнать ID пространства?​

  1. Откройте ваше пространство в консоли EMD Cloud
  2. Посмотрите на URL в адресной строке браузера
  3. ID пространства — это часть URL после /app/

Например, для URL https://console.cloud.emd.one/app/5f2da2f9/database идентификатор пространства — 5f2da2f9.

Интерфейс документации​

Интерактивная документация построена на основе OpenAPI/Swagger и предоставляет удобный интерфейс для работы с API.

Основные элементы​

1. Навигация по разделам​

В левой части экрана расположено дерево разделов API:

  • База данных (Коллекции, Записи, Поля, Представления)
  • Авторизация (Регистрация, Вход, Восстановление пароля)
  • Пользователи (Управление профилями)
  • Хранилище (Файлы)
  • Чаты (Сообщения, Каналы)
  • Вебхуки
  • Сценарии
  • Секреты (Credentials)

2. Список методов​

В центральной части отображается список методов выбранного раздела. Каждый метод помечен цветом в зависимости от HTTP метода:

  • 🟢 GET — получение данных
  • 🟠 POST — создание ресурса
  • 🟡 PUT — полное обновление
  • 🔵 PATCH — частичное обновление
  • 🔴 DELETE — удаление

3. Детали метода​

При выборе метода справа отображаются вкладки:

ПАРАМЕТРЫ

  • Описание всех параметров запроса
  • Обязательные и опциональные поля
  • Типы данных
  • Примеры значений

ЗАГОЛОВКИ

  • Необходимые HTTP заголовки
  • Формат авторизации

ТЕЛО

  • Структура тела запроса (для POST/PUT/PATCH)
  • Схема данных в формате JSON
  • Примеры запросов

АВТОРИЗАЦИЯ

  • Требования к токену
  • Необходимые права доступа

Тестирование запросов​

Интерактивная документация позволяет отправлять реальные запросы к API прямо из браузера.

Как протестировать метод?​

  1. Выберите метод из списка
  2. Заполните параметры в соответствующих полях
  3. Добавьте авторизацию (если требуется)
  4. Нажмите "Выполнить" или "Send"
  5. Изучите ответ — код статуса, заголовки, тело ответа

Авторизация в документации​

Для тестирования защищённых методов необходимо авторизоваться:

  1. Нажмите кнопку "Авторизация" или иконку замка
  2. Введите ваш JWT токен в формате: Bearer YOUR_TOKEN
  3. Сохраните настройки

После этого все запросы будут автоматически включать заголовок авторизации.

подсказка

Получить JWT токен можно через метод /auth/login в разделе "Авторизация" документации.

Схемы данных​

В документации представлены схемы всех объектов API:

Модель (Model)​

Для каждого метода указана структура данных:

  • Названия полей
  • Типы данных (String, Number, Boolean, Object, Array)
  • Обязательность полей (отмечены звёздочкой *)
  • Ограничения и валидация
  • Примеры значений

Пример схемы​

{
  "_id": "String",
  "*name": "String",
  "*email": "String",
  "age": "Number",
  "setting": {
    "*read": "String <'public', 'private', 'only-user'>",
    "*update": "String <'private', 'only-user'>",
    "*write": "String <'public', 'private'>",
    "remove": "String <'private', 'only-user'>"
  }
}

Поля с * обязательны для заполнения.

Примеры запросов​

Для каждого метода документация содержит примеры:

cURL​

curl -X PUT \
  'https://api.emd.one/api/app/5f2da2f9/database' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "_id": "users",
    "name": "Пользователи"
  }'

JavaScript (fetch)​

fetch('https://api.emd.one/api/app/5f2da2f9/database', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    _id: 'users',
    name: 'Пользователи'
  })
})

Коды ответов​

Документация показывает возможные коды ответов для каждого метода:

  • 200 OK — успешное выполнение
  • 201 Created — ресурс создан
  • 400 Bad Request — ошибка в запросе
  • 401 Unauthorized — требуется авторизация
  • 403 Forbidden — недостаточно прав
  • 404 Not Found — ресурс не найден
  • 422 Unprocessable Entity — ошибка валидации
  • 500 Internal Server Error — ошибка сервера

Преимущества интерактивной документации​

✅ Актуальность — документация всегда соответствует текущей версии API

✅ Интерактивность — возможность тестировать запросы без написания кода

✅ Полнота — все методы, параметры и схемы данных в одном месте

✅ Примеры — готовые примеры для разных языков программирования

✅ Специфичность — документация учитывает структуру вашего конкретного пространства

Что дальше?​