API микрослужбы представляет собой контракт между службой и ее клиентами. Вы сможете развивать микрослужбу независимо только в том случае, если не нарушаете ее контракт API; вот почему контракт так важен. Если изменить контракт, это повлияет на клиентские приложения или на шлюз API.
Характер определения API зависит от того, какой протокол используется. Например, при использовании обмена сообщениями (такого как AMQP) API состоит из типов сообщений. При использовании HTTP и службы RESTful API состоит из URL-адресов и форматов JSON запросов и ответов.
Тем не менее, даже если вы внимательно относитесь к первоначальному контракту, со временем API службы потребуется изменить. Когда это происходит, и особенно в том случае, если ваш API является общим API, используемым несколькими клиентскими приложениями, как правило, вы не можете заставить всех клиентов обновиться до вашего нового контракта API. Обычно требуется последовательное развертывание новых версий службы таким образом, чтобы и старая, и новая версии контракта службы работали одновременно. Следовательно, важно иметь стратегию для управления версиями вашей службы.
Если изменения API невелики, например, вы добавили в API атрибуты или параметры, то клиенты, использующие старый API, должны переключиться на новую версию службы и работать с ней. Вы могли бы предоставить значения по умолчанию для каких-либо отсутствующих, но необходимых атрибутов, а клиенты могли бы игнорировать любые лишние атрибуты ответа.
Однако иногда требуется внести в API службы важные и несовместимые изменения. Поскольку вы не сможете обеспечить принудительное немедленное обновление клиентских приложений или служб до новой версии, служба должна некоторое время поддерживать старые версии API. Если используется механизм на основе HTTP, такой как REST, один из подходов заключается во внедрении номера версии API в URL-адрес или в заголовок HTTP. Затем можно либо одновременно реализовать обе версии службы в одном и том же экземпляре службы, либо развернуть разные экземпляры, каждый из которых обрабатывает версию API. Для разделения разных версий реализации по независимым обработчикам рекомендуется использовать шаблон Mediator (например, библиотеку MediatR).
Наконец, при использовании архитектуры REST лучшим решением для управления версиями служб и разрешения развиваемых API является использование гиперсредств.