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

API v2: Планы развития

EMD Cloud активно работает над версией 2.0 API, которая будет полностью соответствовать принципам RESTful архитектуры и современным стандартам разработки API.

Что меняется?​

Полная RESTful архитектура​

API v2 будет строго следовать принципам REST:

  • Единообразные URL — предсказуемая структура эндпоинтов
  • Правильное использование HTTP методов — GET, POST, PUT, PATCH, DELETE по назначению
  • Статусные коды — корректные HTTP коды для всех сценариев
  • HATEOAS — гипермедиа-ссылки в ответах для навигации по API

Улучшенная структура ответов​

{
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Иван Петров",
    "email": "ivan@example.com"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "2.0"
  },
  "links": {
    "self": "/api/v2/users/507f1f77bcf86cd799439011",
    "collection": "/api/v2/users"
  }
}

Версионирование​

API v2 будет доступен по отдельному пути:

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

Текущая версия (v1) продолжит работать по существующим адресам:

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

API v1 будет поддерживаться минимум 2 года после релиза v2, что даёт достаточно времени для миграции.

Новые возможности​

1. GraphQL поддержка​

Помимо REST, планируется добавить GraphQL endpoint для гибких запросов:

query {
  users(filter: { age: { gte: 18 } }, limit: 10) {
    _id
    name
    email
    posts {
      title
      createdAt
    }
  }
}

2. Webhook v2​

Улучшенная система вебхуков с:

  • Retry механизмом — автоматические повторы при ошибках
  • Подписями запросов — проверка подлинности через HMAC
  • Фильтрацией событий — более гранулярный контроль
  • Batch events — группировка событий

3. Rate Limiting​

Прозрачные лимиты запросов с заголовками:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

4. Расширенная фильтрация​

Более мощный язык запросов:

GET /api/v2/users?filter[age][gte]=18&filter[or][0][role]=admin&filter[or][1][role]=manager

5. Partial Responses​

Возможность запрашивать только нужные поля:

GET /api/v2/users?fields=_id,name,email

6. Batch Operations​

Выполнение множественных операций в одном запросе:

POST /api/v2/batch
{
  "operations": [
    {
      "method": "POST",
      "path": "/users",
      "body": { "name": "User 1" }
    },
    {
      "method": "POST",
      "path": "/users",
      "body": { "name": "User 2" }
    }
  ]
}

Улучшения безопасности​

OAuth 2.0​

Поддержка стандартного протокола OAuth 2.0 для авторизации:

  • Authorization Code Flow
  • Client Credentials Flow
  • Refresh Token Flow

API Keys​

Возможность создания API ключей с ограниченными правами:

X-API-Key: emd_live_abc123...

Scopes​

Гранулярные права доступа:

database:read database:write storage:read users:admin

Улучшенная документация​

OpenAPI 3.1​

Полная спецификация API в формате OpenAPI 3.1:

  • Автоматическая генерация клиентов
  • Валидация запросов/ответов
  • Интеграция с популярными инструментами

Интерактивные примеры​

Больше примеров кода на разных языках:

  • JavaScript/TypeScript
  • Python
  • PHP
  • Go
  • Ruby
  • Java
  • C#

Postman коллекции​

Готовые коллекции для Postman с примерами всех методов.

Производительность​

Кэширование​

Поддержка HTTP кэширования с заголовками:

ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Cache-Control: max-age=3600

Сжатие​

Автоматическое сжатие ответов (gzip, brotli).

Pagination Cursors​

Эффективная пагинация для больших наборов данных:

{
  "data": [...],
  "pagination": {
    "next": "eyJpZCI6IjEyMyJ9",
    "prev": "eyJpZCI6IjEwMCJ9",
    "hasMore": true
  }
}

Миграция с v1 на v2​

Совместимость​

API v2 не будет обратно совместим с v1, но мы предоставим:

  1. Руководство по миграции — пошаговая инструкция
  2. Mapping таблицы — соответствие эндпоинтов v1 и v2
  3. Миграционные скрипты — автоматизация перехода
  4. Dual-mode SDK — поддержка обеих версий в SDK

Период перехода​

  • Анонс v2 — за 3 месяца до релиза
  • Beta период — 2 месяца тестирования
  • Релиз v2 — стабильная версия
  • Поддержка v1 — минимум 2 года после релиза v2
  • Deprecation v1 — постепенное выведение из эксплуатации

Обратная связь​

Мы хотим услышать ваше мнение! Если у вас есть предложения по улучшению API v2:

  • GitHub Discussions — обсуждение функций
  • Feature Requests — запросы новых возможностей
  • Beta Testing — участие в тестировании
подсказка

Следите за обновлениями в нашем блоге и changelog, чтобы быть в курсе прогресса разработки API v2.

Ориентировочные сроки​

ЭтапСрок
Публикация спецификацииQ2 2025
Открытая BetaQ3 2025
Стабильный релизQ4 2025
Полная документацияQ4 2025
примечание

Сроки являются ориентировочными и могут измениться в процессе разработки.

Что дальше?​

  • Текущее API — начните работать с существующей версией
  • Примеры — изучите практические примеры
  • SDK — используйте готовые библиотеки