Работа с API

Справочная информация для разработчика

Внутренний API

Internal API, приватный API

Мы разрабатывали внутренний 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:

  1. Откройте Case.one и авторизуйтесь со своим логином и паролем.
  2. Измените адрес в браузерной строке, подставив 'swagger' после имени домена, например: https://yourinstance.case.one/swagger/index.html.

Откроется страница с описанием API.

Теперь просто выберите нужную версию в правом верхнем углу.


Какую версию выбрать?

Давайте разберемся.

Публичный API может быть версии 1.0, 2.0 или 3.0:

  • Если вы давно используете API Case.one, то, возможно, у вас настроена интеграция через API 1.0 — в таком случае, используйте версию 1.0 (она тоже работает, просто содержит меньшее количество конечных точек).
  • Версия 2.0 более полная, охватывает большее количество конечных точек. Если вы новый клиент, мы рекомендуем использовать именно ее.
  • Версия 3.0 содержит группы методов, которые работают через связку Тег — Значение и позволяют обрабатывать сущности Case.one, которые содержат дополнительные атрибуты.

Подведем итоги:

Мы рекомендуем использовать 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?

  1. Обязательно оставьте запрос на доработку публичного API вашему менеджеру.
  2. Если нет возможности ожидать доработок публичного API, то используйте внутренний API, но не забудьте зафиксировать запрос на доработку публичного API.
  3. При использовании внутреннего API обязательно укажите версию используемого API, иначе при выходе нового релиза будет использоваться по умолчанию новая версия API, которая может быть несовместима со старой, что может привести к ошибкам и потере данных.
  4. При появлении необходимых доработок в публичном API замените вызовы внутреннего API на вызовы публичного API как можно скорее, чтобы избежать ошибок, описанных выше.