Управление версиями

Версия Partner API указывается в URL-адресе. Текущая версия:

https://partner-api.performancehub.co/partner/v1/

Политика изменений

По возможности Performance Hub стремится вносить дополняющие изменения с сохранением обратной совместимости.

Примеры изменений с обратной совместимостью:

• Добавление нового необязательного поля в запрос.
• Добавление нового поля в ответ.
• Добавление новой конечной точки.
• Добавление нового значения перечисления, если клиенты должны обрабатывать неизвестные значения.
• Улучшение сообщений проверки без изменения контракта кодов состояния.

access_time_windows и access_time_windows_revision — дополнительные поля запроса Member. У существующих клиентов, которые их не указывают, сохраненный снимок Access Time Windows остается без изменений. Это правило опускания сохраняет совместимость с частичными операциями upsert; опускание поля не равнозначно отправке пустого массива.

Примеры изменений, нарушающих совместимость:

• Удаление или переименование поля.
• Изменение типа поля.
• Превращение необязательного поля запроса в обязательное.
• Удаление конечной точки.
• Изменение значения существующего кода состояния или предметного reason.

Вывод из использования

Если требуется изменение, нарушающее совместимость, Performance Hub по возможности не будет изменять существующую версию на месте. Вместо этого мы представим новую версию или путь миграции и сообщим об изменении затронутым партнерам.

Уведомления о выводе из использования могут включать:

• Запись в журнале изменений.
• Прямое информирование партнеров.
• Примечания в Partner Console.
• Рекомендации по миграции в документации.

Рекомендации для клиентов

Создавайте клиенты, устойчивые к дополняющим изменениям:

• Игнорируйте поля ответа, которые вы не используете.
• Рассматривайте неизвестные значения перечислений как неподдерживаемые, а не завершайте работу аварийно.
• Избегайте строгих проверок на точное совпадение ответов.
• Регистрируйте нераспознанные значения, чтобы обновлять интеграцию осознанно.

Для разделов Member с ревизиями, таких как Access Time Windows, сохраняйте отправленную ревизию и нормализованную полезную нагрузку, пока не станет известен результат. Повторное использование ревизии для измененного содержимого приводит к конфликту, а повторная отправка того же содержимого идемпотентна. См. раздел Access Time Windows.

Спецификации OpenAPI

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

См. раздел Спецификации OpenAPI.