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

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.

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

В ходе раннего развития сервис-ориентированной архитектуры появились такие стандарты, как Universal Description, Discovery и объединенный стандарт Integration (UDDI), помогающие людям разобраться в том, какие сервисы были запущены. Эти подходы были весьма тяжеловесными, что приводило к появлению альтернативных технологий, с помощью которых осуществлялись попытки разобраться в наших системах. Мартин Фаулер рассмотрел концепцию понятного человеку реестра, в рамках которой использовались намного более легкие подходы, предназначенные просто для того, чтобы люди могли записывать информацию о сервисах в организациях в чем-то таком же простом, как вики.