Создание микросервисов

Разбиением систем на узкоспециализированные микросервисы мы надеемся показать множество стыков в виде API-интерфейсов, которые люди могут использовать для создания многих, надеюсь, замечательных вещей. Если обнаружение проведено правильно, мы знаем, где что есть. Но как узнать, чем все это занимается или как всем этим пользоваться? Один из очевидных вариантов заключается в применении документации, описывающей API-интерфейсы. Разумеется, документация может часто устаревать. В идеале хотелось бы обеспечить постоянное соответствие документации состоянию API-интерфейса микросервиса и облегчить просмотр этой документации, когда мы знаем, где находится конечная точка сервиса. Воплотить это в реальность пытаются две различные технологии, Swagger и HAL, и обе они заслуживают рассмотрения.

Swagger

Swagger позволяет описать API-интерфейс, чтобы можно было создать весьма функциональный пользовательский веб-интерфейс, позволяющий просматривать документацию и взаимодействовать с API-интерфейсом посредством браузера. Особенно подкупает возможность выполнения запросов: вы можете, к примеру, определить POST-шаблоны, разъясняя, какого сорта контент ожидается сервером.

Чтобы справиться со всем этим, Swagger нуждается в сервисе для выставления сопутствующего файла, соответствующего Swagger-формату. У Swagger имеется ряд библиотек для различных языков программирования, которые делают все это за вас. Например, для Java можно комментировать методы, соответствующие API-вызовам, а для вас будет создан соответствующий файл.

Мне нравится то впечатление, которое оставляет Swagger у конечного пользователя, но оно мало что дает для концепции дополнительных исследований на основе гиперсреды. И все же это очень хорошее средство показа документации, дающей представление о ваших сервисах.

HAL и HAL-браузер

Сам по себе язык гипертекстовых приложений (HAL) является стандартом, в котором описываются положения, касающиеся выставляемых нами элементов управления гиперсредой. Как уже говорилось в главе 4, элементы управления гиперсредой являются средствами, с помощью которых мы позволяем клиентам постепенно исследовать API-интерфейсы, чтобы применять возможности наших сервисов без задействования такой же сильной связанности, которая используется другими технологиями интеграции. Если вы решите применять стандарты гиперсреды, заложенные в HAL, то это позволит вам воспользоваться не только большим количеством клиентских библиотек для применения API-интерфейса (на момент написания данной книги в статье «Википедии», посвященной HAL, перечислялись 50 поддерживающих его библиотек для множества различных языков), но и HAL-браузером, предоставляющим способ исследования API с помощью браузера.

Как и Swagger, этот пользовательский интерфейс может применяться не только как живая документация, но и как средство, выполняющее вызовы самого сервиса. Хотя выполнение вызовов происходит не так же гладко. Если при использовании Swagger можно определять шаблоны для выполнения таких операций, как выдача POST-запросов, с HAL вы больше полагаетесь на собственные силы. В то же время присущая элементам управления гиперсредой эффективность позволяет намного продуктивнее исследовать API-интерфейс, демонстрируемый сервисом, поскольку дает возможность легко и просто следовать по ссылкам. Оказывается, браузеры великолепно справляются и с этими задачами!

В отличие от Swagger, все информация, необходимая для управления данной документацией и «песочницей», встроена в элементы управления гиперсредой. Но это обоюдоострый меч. Если вам уже приходилось использовать элементы управления гиперсредой, то больших усилий для показа HAL-браузера и предоставления клиентам возможности исследования вашего API-интерфейса не понадобится. Но если вам не приходилось пользоваться гиперсредой, то либо вы не сможете применять HAL, либо вам придется подгонять свой API-интерфейс под использование гиперсреды, что, скорее всего, станет занятием, нарушающим нормальную работу текущих потребителей.

Тот факт, что в HAL также дается описание стандартов гиперсреды с поддержкой клиентских библиотек, является дополнительным бонусом, и я полагаю, что именно в этом кроется весомая причина, по которой среди тех, кто уже имеет опыт применения элементов управления гиперсредой, наблюдается больше сторонников использования HAL, чем сторонников применения Swagger в качестве способа документирования API-интерфейсов. Если вы используете гиперсреду, то я советую отдать предпочтение HAL, а не Swagger. Однако если вы используете гиперсреду, но не видите оснований для перехода на HAL, я настоятельно рекомендую пустить в дело Swagger.

Самостоятельно описываемая система