Мы разрабатывали внутренний API специально для нужд пользовательского интерфейса Case.one и не рекомендуем использовать его для других целей.
Мы не рекомендуем использовать внутренний API для интеграции с Case.one.
Изменения внутреннего API синхронизированы с основным циклом разработки и публикуются с каждый новым релизом.
Правила внутреннего API, которые полезно знать:
С каждым релизом публикуется новая версия внутреннего API
Номер версии внутреннего API совпадает с номером релиза
Мы поддерживаем только текущую и предыдущую версию внутреннего API в основной части приложения, и только текущую версии API в админке — если вы работаете с внутренним API, вам необходимо проставить версионность и обновлять ее по мере обновлений Case.one
Версионность указывается в URL запроса, например: https://yourinstance.case.one/swagger/index.html?urls.primaryName=v62
Если версия API не указана, то обращение идет к последней доступной версии API
Если у вас остались вопросы по работе с API — воспользуйтесь нашими ответами в разделе Часто задаваемые вопросы.
Публичный API
API, публичный API, версия API, авторизация
В Case.one мы используем внутренний и публичный API. См. подробнее: Какие типы API есть?
Публичный API мы разработали специально для внешних потребителей сервиса Case.one, таких как:
Интеграции со сторонними системами
Мобильные приложения
Скрипты в сценариях автоматизации
Для доступа к API:
Откройте Case.one и авторизуйтесь со своим логином и паролем.
Теперь просто выберите нужную версию в правом верхнем углу.
Какую версию выбрать?
Давайте разберемся.
Публичный API может быть версии 1.0, 2.0, 3.0 или 4.0:
Если вы давно используете API Case.one, то, возможно, у вас настроена интеграция через API 1.0 — в таком случае, используйте версию 1.0 (она тоже работает, просто содержит меньшее количество конечных точек)
Версия 2.0 более полная, охватывает большее количество конечных точек. Если вы новый клиент, мы рекомендуем использовать именно ее
Версия 3.0 содержит группы методов, которые работают через связку Тег — Значение и позволяют обрабатывать сущности Case.one, которые содержат дополнительные атрибуты
Версия 4.0 содержит группы методов, позволяющие:
Настраивать права для роли
Обрабатывать новые системные поля карточки участника Телефон и Электронная почта
Подведем итоги:
Мы рекомендуем использовать PUBLIC API VERSION 2.0 в своих разработках.
Чтобы выбрать его, нажмите в поле Select a definition и выберите версию v2.
Если у вас остались вопросы по работе с API — воспользуйтесь нашими ответами в разделе Часто задаваемые вопросы.
Как ориентироваться в Swagger?
Описание публичного и внутреннего API доступно по ссылке:
https://yourinstance.case.one/swagger/index.html
Измените адрес в браузерной строке, подставив 'swagger' после имени домена.
В верхней части экрана расположен выпадающий список для выбора версии API.
После выбора версии появится информация о выбранной версии API.
Для версии публичного API будет указано Public API version 1.0, для внутреннего — Internal API version 63.0.
Далее идет список методов API, сгруппированных по типу сущности.
Как правильно выбрать версию API?
Как правильно выбрать версию при работе с публичным API вы можете посмотреть здесь.
При работе с внутренним API следует придерживаться следующих правил:
Обязательно указывать версию используемого API
Для всех измененных API необходимо обязательно перейти на использование новой версии, так как к следующему релизу поддержка предыдущей версии прекратится
Какие типы API есть, в чем разница?
Какие типы API есть (внутренний, публичный), в чем разница, для чего использовать, что использовать в первую очередь?
В Case.one есть два вида API — публичный и внутренний.
Мы разработали внутренний API специально для нужд пользовательского интерфейса web-приложения Case.one, поэтому его не рекомендуется использовать для других целей.
Публичный API мы разработали для внешних потребителей сервиса Case.one, таких как:
Интеграции со сторонними системами
Мобильные приложения
Скрипты в сценариях автоматизации
Основные отличия внутреннего и публичного API обусловлены тем, что изменения внутреннего API синхронизированы с основным циклом разработки и изменениями вносимыми в пользовательский интерфейс — то есть публикуются синхронно с каждый новым релизом, и внутренний API всегда согласован с пользовательским интерфейсом.
Публичный же API предназначен специально для настройки интеграций и скриптов автоматизации.
Свойства внутреннего API:
С каждым релизом публикуется новая версия внутреннего API
Номер версии внутреннего API совпадает с номером релиза
Гарантируется поддержка только текущей и предыдущей версии внутреннего API в основной части приложения, и только текущей версии API в админке — если вы работаете с внутренним API, вам необходимо проставить версионность и обновлять по мере обновлений Case.one
Используемая версия внутреннего API указывается в параметрах запроса в URL запроса (например, https://yourinstance.case.one/swagger/index.html?urls.primaryName=v62)
Если версия API не указана, то обращение идет к последней доступной версии API
Свойства публичного API:
Новая версия публичного API публикуется, когда в публичном API появляются изменения, не обладающие обратной совместимостью с предыдущей версией API, т.е. в том случае, когда запрос к старой версии API не может быть обработан новой версией API
Версии публичного API нумеруются последовательно (начиная с 1.0)
Используемая версия публичного API указывается в сегменте URL запроса, обратиться к публичному API, не указав версию, невозможно (например, https://yourinstance.case.one/swagger/index.html?urls.primaryName=v3)
Во всех кейсах взаимодействия с API Case.one рекомендуется использовать публичный API.
Что чаще всего меняется: публичный API или внутренний API?
Чаще всего меняется внутренний API, поэтому выделить какой-то диапазон методов сложно — набор реализуемых функций очень широкий, и изменения могут быть в любом месте.
Отдельно можно выделить только админку — в админке мы поддерживаем только текущую версию внутреннего API, поэтому его не следует использовать.
Как часто нужно подстраиваться под правки?
При использовании публичного API правки скриптов не нужны, кроме тех случаев, когда вам потребовались новые возможности публичного API.
При использовании внутреннего API мы вносим правки каждый релиз.
Почему API меняется, где публикуется информация об изменениях, как понимать разницу между версиями?
Публичный API:
Меняется, потому что был запрос на доработку API.
Так как публичный API меняется по запросу, то информация об изменениях публичного API вы можете увидеть в описаниях новых версий Case.one.
Внутренний API меняется, потому что при разработке новых фич в пользовательский интерфейс вносятся изменения, которые требуют доработок внутреннего API, которое предоставляет данные для пользовательского интерфейса (собственно только для этого внутренний API и существует).
Информация об изменениях внутреннего API, которые не совместимы с предыдущими версиями внутреннего API доступно в diff-версии, которая предоставляется в отдельном файле.
Что делать, если нет нужных методов публичного API?
Обязательно оставьте запрос на доработку публичного API вашему менеджеру.
Если нет возможности ожидать доработок публичного API, то используйте внутренний API, но не забудьте зафиксировать запрос на доработку публичного API.
При использовании внутреннего API обязательно укажите версию используемого API, иначе при выходе нового релиза будет использоваться по умолчанию новая версия API, которая может быть несовместима со старой, что может привести к ошибкам и потере данных.
При появлении необходимых доработок в публичном API замените вызовы внутреннего API на вызовы публичного API как можно скорее, чтобы избежать ошибок, описанных выше.
