Описание публичного и внутреннего 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 как можно скорее, чтобы избежать ошибок, описанных выше.