^{Какие типы 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 передается дата и время
  • Время передается с точностью до секунды