Версии и совместимость

Версия API — в адресе: https://api.gratio.net/v1/instances/{idInstance}/{метод}. Внутри /v1 API только растёт: интеграция, написанная сегодня, продолжит работать после обновлений Gratio.

Что меняется без предупреждения

Добавления. Код, который пропускает незнакомое, их не заметит:

• новые методы;
• новые необязательные параметры;
• новые поля в ответах и уведомлениях;
• новые виды уведомлений (typeWebhook), сообщений (typeMessage) и событий групп;
• новые значения в перечислениях: статусы, причины reason, endReason, code отказов;
• текст message в ошибках — он для людей, а не для кода.

Каждое добавление попадает в История изменений.

Что объявляется заранее

Изменения, которые могут сломать интеграцию:

• метод, параметр или поле убирают или переименовывают;
• меняется тип или формат поля;
• параметр становится обязательным;
• на тот же случай меняется код ответа или форма отказа.

Такое изменение появляется в История изменений заранее — с пометкой «Изменение», датой и сроком перехода. До срока прежняя форма работает вместе с новой: переходите, когда удобно.

Как писать код

• Пропускайте незнакомое. Неизвестное поле, typeWebhook или typeMessage — не ошибка: сохраните или пропустите и ответьте 200.
• Ветвитесь по code, а не по message. Текст ошибки может меняться.
• Не полагайтесь на порядок полей и на то, что поле есть у всех видов уведомлений.
• Храните id строками. Исключение — idInstance, номер канала, — число. См. Идентификаторы чатов и сообщений.
• Проверяйте возможности, а не канал. Что умеет канал, отвечает getCapabilities: новые возможности появляются в ответе, как только включены.

Что дальше

• История изменений — что нового по версиям.
• Ответы и ошибки — коды и что повторять.
• Формат уведомления — общие поля уведомлений.