Какие типы 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 — будут возвращены заголовок и ссылка в формате: [заголовок] (ссылка)
- Вы можете настроить параметр isFormattedTextEnabled, чтобы выбрать, в каком формате будет отображаться полученный текст из полей:
- Все методы публичного API, которые позволяют загружать документы, выполняют проверку файлов изображений — при попытке загрузить «битое» изображение, или изображение в формате, отличном от *.gif, *.jpg, *.jpe, *.jpeg и *.png:
- Изображение загружено не будет
- В логах появится запись об ошибке
- Вы можете получать и задавать через API поля с типом Дата и Время:
- В API передается дата и время
- Время передается с точностью до секунды