Какие типы 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.