Новая версия внешнего API для получения новостей Newsfeed (реализовано)

[Tozarin]

Новая версия API для Newsfeed-сервиса

Сервис Newsfeed изменил точку входа для получения новостной ленты. Старый эндпоинт будет выведен из эксплуатации. Необходимо адаптировать наш код.

• Было (v1):

  • GET https://api.netbox.oss.netboxlabs.com/v1/newsfeed/

• Стало (v2):

  • GET https://api.netbox.oss.netboxlabs.com/newsfeed/?version=2

Обоснование

1. Унификация версионирования: переход к query-параметрам для указания версии API упрощает маршрутизацию и кэширование
2. Расширенный формат ответа: новая версия предоставляет дополнительные метаданные и улучшенную структуру данных
3. Готовность к расширению: query-параметры позволяют добавлять фильтры без изменения базового URL

📋 Статус реализации

✅ Выполненные задачи

1. Параметры конфигурации (netbox/config/parameters.py)

Добавлен параметр: NEWSFEED_API_VERSION

• Тип: String
• По умолчанию: 'v1'
• Описание: Версия API новостной ленты для использования (v1 или v2)
• Возможные значения:
  • 'v1' - использует endpoint https://api.netbox.oss.netboxlabs.com/v1/newsfeed/
  • 'v2' - использует endpoint https://api.netbox.oss.netboxlabs.com/newsfeed/?version=2
  • любое другое значение - fallback на базовый URL

2. Конфигурация настроек (netbox/settings.py)

Логика определения URL:

• Если NEWSFEED_API_VERSION == 'v1':
  • NEWSFEED_URL = f'{NETBOX_API_BASE_URL}v1/newsfeed/'
• Если NEWSFEED_API_VERSION == 'v2':
  • NEWSFEED_URL = f'{NETBOX_API_BASE_URL}newsfeed/?version=2'
• Иначе:
  • NEWSFEED_URL = f'{NETBOX_API_BASE_URL}newsfeed/' (базовый URL)

3. Конфигурация виджета дашборда (extras/constants.py)

Обновлено: Конфигурация RSSFeedWidget

• Было: Жестко заданный URL 'https://api.netbox.oss.netboxlabs.com/v1/newsfeed/'
• Стало: Динамический URL из настроек settings.NEWSFEED_URL

4. Дополнительные улучшения

✅ Добавлены автоматические тесты (extras/tests/test_newsfeed.py):

• Тесты конфигурации (v1, v2, fallback)
• Тесты виджета с динамическим URL
• Тесты для изолированных развертываний

✅ Создана документация (NEWSFEED_API_MIGRATION.md):

• Полное описание изменений
• Инструкция по миграции
• План тестирования и отката

✅ Создан скрипт тестирования (test_newsfeed_migration.py):

• Проверка конфигурации
• Валидация URL для разных версий
• Проверка интеграции с виджетом

Стратегия обратной совместимости

Реализован механизм конфигурируемого переключения версий:

1. По умолчанию используется v1 - обеспечивает обратную совместимость
2. Переключение на v2 через конфигурационный параметр:

   NEWSFEED_API_VERSION = 'v2'

3. Fallback механизм - при указании неизвестной версии используется базовый URL
4. Плавный переход - администраторы могут переключиться на v2 в удобное время

Риски и влияние

• ✅ Обратная совместимость: v1 работает по умолчанию
• ✅ Конфигурируемость: Легкое переключение между версиями
• ⚠️ Изменение формата ответа: v2 может возвращать расширенный формат (обрабатывается библиотекой feedparser)
• ⚠️ Отсутствие автоматического fallback: Требует ручного переключения при проблемах с v2

🧪 Тестирование

Автоматические тесты

# Запуск тестов Newsfeed API
python manage.py test extras.tests.test_newsfeed

# Запуск скрипта проверки миграции
python test_newsfeed_migration.py

Ручное тестирование

1. Проверка v1 (по умолчанию):

   • Виджет "NetBox News" отображает данные через v1 API
   • Конфигурационный параметр равен v1

2. Проверка v2:

   • Установить NEWSFEED_API_VERSION = 'v2' в настройках
   • Виджет использует новый endpoint ?version=2
   • Данные корректно отображаются

3. Проверка fallback:

   • Установить неизвестную версию (например, v3)
   • Система использует базовый URL

Чеклист задач

• Добавить параметр конфигурации NEWSFEED_API_VERSION
• Реализовать логику выбора URL на основе версии в settings.py
• Обновить виджет дашборда для использования динамического URL
• Обновить MAPS_URL до актуального API (отложено - нет дополнительных данных)
• Создать документацию по миграции API
• Провести тестирование на стенде с v2 API
• Обновить конфигурацию production после проверки (требует ручного развертывания)

📚 Документация

Полная документация доступна в файле NEWSFEED_API_MIGRATION.md, включая:

• Детальное описание изменений
• Инструкция по переходу на v2
• План миграции и отката
• Руководство по тестированию

🚀 Развертывание

1. Текущее состояние: Все экземпляры используют v1 по умолчанию
2. Тестирование: Переключить тестовые среды на v2 (NEWSFEED_API_VERSION = 'v2')
3. Продакшен: После успешного тестирования обновить продакшен среды
4. Мониторинг: Следить за доступностью Newsfeed API и отображением виджета

📞 Поддержка

При возникновении проблем:

1. Проверьте логи приложения
2. Убедитесь в доступности Newsfeed API
3. Проверьте значение NEWSFEED_API_VERSION в настройках
4. При необходимости вернитесь на v1 и создайте issue