Требования к версионированию Открытых API направлены на управление изменениями и обновлениями API участников без нарушения работы существующих интеграций.
Основные правила версионирования включают:
Мажорные версии:
- Определение: Включают значительные изменения, которые могут быть несовместимы с предыдущими версиями.
- Пример: Переход от версии 1.0 к 2.0.
- Правила:
- Мажорная версия должна быть выпущена при внесении изменений, которые нарушают обратную совместимость.
- Пользователи должны быть уведомлены заранее о предстоящем выпуске новой мажорной версии.
- Рекомендация по количеству поддерживаемых версий: Рекомендуется поддерживать как минимум две последние мажорные версии для обеспечения плавного перехода пользователей.
- Сроки применения изменений пользователями: Пользователям должно быть предоставлено не менее 12 месяцев для перехода на новую мажорную версию после её выпуска.
Минорные версии:
- Определение: Включают новые функции, которые совместимы с предыдущими версиями.
- Пример: Переход от версии 1.0 к 1.1.
- Правила:
- Минорная версия должна быть выпущена при добавлении новых функций, не нарушающих работу существующих интеграций.
- Документация должна быть обновлена с подробным описанием новых возможностей и инструкциями по их использованию.
- Рекомендация по количеству поддерживаемых версий: Рекомендуется поддерживать текущую минорную версию и предшествующую ей версию в рамках одной мажорной версии.
Патч-версии:
- Определение: Включают исправления ошибок и улучшения безопасности, не влияющие на функциональность.
- Пример: Переход от версии 1.0.0 к 1.0.1.
- Правила:
- Патч-версия должна быть выпущена при внесении мелких исправлений и улучшений.
- Изменения должны быть документированы и донесены до пользователей через обновления документации.
- Рекомендация по количеству поддерживаемых версий: Патчи должны поддерживаться для всех активных мажорных и минорных версий.
Жизненный цикл API охватывает все этапы от разработки до устаревания. Основные фазы управления жизненным циклом API включают:
Разработка:
- Описание: Этап создания и тестирования новых API.
- Правила:
- API должны быть разработаны с учетом требований безопасности, производительности и совместимости.
- Включение всех необходимых механизмов для тестирования и отладки.
Тестирование:
- Описание: Проверка API на соответствие требованиям и отсутствие ошибок.
- Правила:
- Проведение различных типов тестирования, включая функциональное, нагрузочное и безопасность.
- Доступ к тестовой среде для разработчиков третьих лиц.
Выпуск:
- Описание: Официальное представление API пользователям.
- Правила:
- Публикация подробной документации и примеров использования.
- Обеспечение поддержки и канала обратной связи для пользователей.
Поддержка:
- Описание: Обеспечение функционирования API и решение возникающих проблем.
- Правила:
- Регулярные обновления для исправления ошибок и улучшения безопасности.
- Четко определенные сроки поддержки для каждой версии API.
- Сроки поддержки старых версий:
- Мажорные версии: Поддержка старых мажорных версий должна сохраняться в течение как минимум 18 месяцев после выпуска новой мажорной версии.
- Минорные версии: Поддержка минорных версий в рамках одной мажорной версии должна сохраняться в течение 12 месяцев после выпуска новой минорной версии.
Устаревание:
- Описание: Процесс прекращения поддержки устаревших версий API.
- Правила:
- Уведомление пользователей о планируемом устаревании заранее.
- Обеспечение периода поддержки параллельно с новыми версиями для плавного перехода.
- Документация по миграции на новые версии API.
- Сроки уведомления: Пользователи должны быть уведомлены не менее чем за 12 месяцев до окончания поддержки.
Отключение :
- Описание: Полное прекращение поддержки и работы API.
- Правила:
- Предоставление пользователям четкого графика и инструкций по миграции.
- Обеспечение доступности архивной документации для исторических целей.
- Сроки отключения: Окончательное отключение API должно происходить не ранее чем через 6 месяцев после завершения периода устаревания.