Перейти на сайт Case.one

Вопросы по API

Какие типы API есть, в чем разница?

Какие типы API есть (внутренний, публичный)? В чем разница? Для чего использовать? Что использовать в первую очередь?

В Case.one есть два вида API — публичный и внутренний.

Мы разработали внутренний API специально для нужд пользовательского интерфейса web-приложения Case.one, поэтому его не рекомендуется использовать для других целей.

Публичный API мы разработали для внешних потребителей сервиса Case.one, таких как:

  • Интеграции со сторонними системами.
  • Мобильные приложения.
  • Скрипты в сценариях автоматизации.

В публичном и приватном API предусмотрено общее ограничение на максимальный размер запрашиваемой страницы в 100 элементов без паджинации для следующих списков:

  • Список типов блоков в дашборде.
  • Список форматов полей в конструкторе типов объектов.
  • Список классов объектов в режиме администрирования.
  • Список таймлогов на панели AI-Ассистента в календаре.

Основные отличия внутреннего и публичного 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

  • Используется метод описания REST API.
  • Все сущности создаются в 1 запрос, включая создание объекта (дела).
  • Поддерживается версионирование публичного API — вносимые в систему изменения не нарушают работоспособность клиентов, работающих с предыдущей версией API.
  • Если у сущности есть дополнительные атрибуты, вы можете в одном запросе создавать, изменять или просматривать данные с доп. параметрами.
  • Запросы выполняются от имени аутентифицированного пользователя:
    • Методы API учитывают права пользователя
    • Если пользователь заблокирован, он не может выполнять запросы по API
  • Во всех методах публичного API, где возвращается форматированный текст:
    • Вы можете настроить параметр isFormattedTextEnabled, чтобы выбрать, в каком формате будет отображаться полученный текст из полей:
      • Если isFormattedTextEnabled — True, возвращается текст с HTML-разметкой (значение по умолчанию)
      • Если isFormattedTextEnabled — False, возвращается текст без разметки (PlianText)
      • Если isFormattedTextEnabled не указан, значение параметра будет взято из настройки IsFormattedTextInPublicApiEnabled в файле конфигурации (это позволяет не исправлять текущие скрипты, которые используют методы, добавляя в них параметр isFormattedTextEnabled)
    • Поскольку в форматированном тексте может содержаться ссылка в тексте заголовка, в файле конфигурации вы можете настроить параметр LinkFormatInPlaintText — для настройки того, как ссылка будет преобразована в PlainText (который отображается в отчетах, при формировании документов, в условиях доступности, в сценариях автоматизации и т.д.) выберите значение:
      • text — будет возвращен только заголовок (значение по умолчанию)
      • url — будет возвращена только ссылка
      • both — будут возвращены заголовок и ссылка в формате: [заголовок] (ссылка)
  • Все методы публичного API, которые позволяют загружать документы, выполняют проверку файлов изображений — при попытке загрузить «битое» изображение, или изображение в формате, отличном от *.gif, *.jpg, *.jpe, *.jpeg и *.png:
    • Изображение загружено не будет
    • В логах появится запись об ошибке
  • Вы можете получать и задавать через API поля с типом Дата и Время:
    • В API передается дата и время
    • Время передается с точностью до секунды

Как правильно выбрать версию API?

Как правильно выбрать версию при работе с публичным API вы можете посмотреть здесь.

При работе с внутренним 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 может быть версии 1.0, 2.0, 3.0 или 4.0:

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

Почему API меняется, где публикуется информация об изменениях, как понимать разницу между версиями?

Публичный API меняется, потому что был запрос на доработку API. Поскольку публичный API меняется по запросу, то информация об изменениях публичного API вы можете увидеть в описаниях новых версий Case.one.

Внутренний API меняется, потому что при разработке новых фич в пользовательский интерфейс вносятся изменения, которые требуют доработок внутреннего API, которое предоставляет данные для пользовательского интерфейса (собственно только для этого внутренний API и существует).

Информация об изменениях внутреннего API, которые не совместимы с предыдущими версиями внутреннего API доступно в diff-версии, которая предоставляется в отдельном файле.

Что чаще всего меняется: публичный API или внутренний API?

Чаще всего меняется внутренний API, поэтому выделить какой-то диапазон методов сложно — набор реализуемых функций очень широкий, и изменения могут быть в любом месте.

Отдельно можно выделить только админку — в админке мы поддерживаем только текущую версию внутреннего API, поэтому его не следует использовать.

Как часто нужно подстраиваться под правки?

При использовании публичного API правки скриптов не нужны, кроме тех случаев, когда вам потребовались новые возможности публичного API.

При использовании внутреннего API мы вносим правки каждый релиз.

Как ориентироваться в Swagger?

Все методы API (публичного и внутреннего) доступны в Swagger по ссылке следующего вида:

https://yourinstance.case.one/swagger/index.html

Чтобы начать работу с публичным API:

  1. Откройте Case.one и авторизуйтесь со своим логином и паролем для просмотра параметров сущности (например, идентификатор дела).
  2. Измените адрес в строке браузера, подставив swagger после имени домена инстанса Case.one, например: https://yourinstance.case.one/swagger/index.html. Откроется страница с описанием API.
  3. Выберите версию API в поле Select a definition. Отобразится API выбранной версии:
    • Для версии публичного API в заголовке будет указано Public API version X.0, для внутреннего — Internal API version XX.0, где X — номер версии
    • После заголовка отображается список методов API, сгруппированных по типу сущности
    • Рядом с названием группы методов приведено общее описание

Для внутреннего API поддерживаются только две версии:

  • Версия текущего релиза.
  • Версия предыдущего релиза.

Чтобы выбрать конкретный метод:

  1. Выберите группу методов и нажмите кнопку .
  2. Выберите метод и нажмите кнопку . Раскроется подробная информация о методе:
    • Описание конкретного метода
    • Описание необходимых заголовков
    • Описание входных параметров с типами
    • Описание возможных вариантов результата

Что делать, если нет нужных методов публичного API?

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