AWS WebSocket: написание документации с помощью Async API Spec.
Предыдущие части: Часть 1, Часть 2
Помните свою последнюю интеграцию со сторонним API? Как вы ее реализовали? Было легко?
Первый шаг в любой интеграции — это изучение документации. Если документации нет, то шанс успеха стремится к 0%.
Часть разработки ПО, которую разработчики обычно ненавидят так же сильно, как написание модульных тестов — это создание документации для API. К их сожалению, она необходима, если, конечно, разработчик ?
AWS WebSocket: написание документации с помощью Async API Spec...
Предыдущие части: Часть 1, Часть 2
Помните свою последнюю интеграцию со сторонним API? Как вы ее реализовали? Было легко?
Первый шаг в любой интеграции — это изучение документации. Если документации нет, то шанс успеха стремится к 0%.
Часть разработки ПО, которую разработчики обычно ненавидят так же сильно, как написание модульных тестов — это создание документации для API. К их сожалению, она необходима, если, конечно, разработчик желает добиться успеха со своими интеграторами.
Мы сосредоточимся на документировании API при помощи спецификации Async API, которая позволяет вместо endpoints определять channels (каналы), которые описывают, как пользователь может взаимодействовать с системой.
Спецификация Async API
API, который мы к этому моменту создали в AWS, обеспечивает два событийных взаимодействия:
- WebSocket, на который пользователи могут подписываться для получения уведомлений об обновлении сущностей;
- событие EventBridge, которое активирует push-уведомление в WebSocket.
В случае традиционной спецификации Open API у нас нет возможности проинформировать потребителей о схемах, информации подключения или возможных взаимодействиях с событиями. Данная спецификация создавалась для описания других вещей, а именно синхронных конечных точек REST API.
А вот спецификация Async API создавалась именно для этого. Она документирует управляющие поведением события и показывает взаимодействия publish и subscribe, которые пользователь может совершать в нашем WebSocket.
Для начала работы с этой спецификацией переключитесь на ветку part-three в репозитории serverless-websockets на GitHub следующей командой:
git fetch
git checkout part-three
Имейте в виду — это предполагает, что вы уже клонировали репозиторий, и он имеется у вас в локальном доступе.
Компоненты спецификации
Спецификация Async API состоит из нескольких частей, которые предоставляют информацию о разных аспектах API. Ниже мы разберем те из них, которые потребуются нам для составления документации к нашему WebSocket.
Первая часть любой спецификации API описывает общее назначение. Здесь мы сообщаем потребителю, для чего предназначен этот API. В нашем примере мы приводим некоторую высокоуровневую информацию, которая поясняет пользователю, что находится в спецификации.
Эта спецификация поддерживает использование в компоненте description языка Markdown, так что ваша документация сможет отображать богатый, хорошо отформатированный текст.
Детали подключения
Пожалуй, наиболее важной частью спецификации является информация о подключении. Пользователю необходимо знать, как подключаться к API, а также базовый url каждой среды.
Все это содержится в разделе servers. Поскольку наш WebSocket API требует предоставления access_token, его необходимо сюда включить.
Для WebSocket с безопасными подключениями всегда используется протокол wss. Незашифрованные подключения задействуют протокол ws. Поскольку наш WebSocket API имеет безопасное соединение и требует токена аутентификации, здесь мы используем wss.
Перечисление событий
При использовании спецификации Async API события содержатся в channels. Канал — это простой способ организации событий в событийно-ориентированном API. Для нашего сценария нам нужно, чтобы все связанные с WebSocket события находились в одном канале, а событие EventBridge, активирующее push-уведомления, в другом.
В каждом канале содержатся опции для publish и subscribe. Если взглянуть с позиции потребителя спецификации, то нахождение события в разделе publish означает, что потребитель может опубликовать его в API. События из раздела subscribe — это те, которые потребитель будет получать от API.
В спецификации нам нужно также сообщить пользователю, какой сервис AWS он будет использовать для публикации или подписки на конкретное событие. Делается это с помощью tags. Под каждым разделом publish или subscribe в каждом канале мы добавляем тег, обозначающий систему, которая активирует событие.
Описание событий с помощью JSON Schema
Чтобы обеспечить клиентам лучший опыт работы с нашей спецификацией, необходимо описать схемы событий, которые API получает/производит. Для этого мы описываем полезные нагрузки в разделе messages спецификации.
Как видно на скриншоте выше, разделы publish и subscribe каждого канала содержат ссылку ($ref) на сообщение. Эта ссылка несет информацию, специфичную для этого сообщения, например title, summary и любые examples, которые мы хотим показать потребителю.
Объект payload содержит ссылку на объект JSON Schema, который описывает свойства события. Это информирует потребителя о том, как конкретно определять событие при публикации или как писать код, который потребляет описанное событие. Существуют даже онлайн-инструменты, которые генерируют примеры из JSON Schema (и наоборот).
Для каналов, которые содержат в разделах publish или subscribe много сообщений можно использовать объект JSON Schema oneOf. Это сообщит потребителю, что сообщение, которое публикуется или на которое подписываются через этот канал, может представлять один из нескольких вариантов.
При условии четко выраженного посыла в разделах messages и schema ваши потребители будет точно понимать, что использовать.
Создание собственной спецификации
Иногда создание новой спецификации с нуля или даже внесение изменений в существующую оказывается непростой задачей. К счастью, существует ряд бесплатных инструментов, которые этот процесс упрощают.
Документация является ключом к успешной работе с интеграторами как внутренне, так и внешне. Если ваша информация о событиях и подключении нигде не задокументирована, то в итоге вы будете опираться на локальные знания, которые сложно поддерживать даже внутри организации и невозможно за ее пределами.
Благодаря Async API мы имеем возможность четко указать, какие схемы имеют наши события, какие используются каналы, какие события потребитель может публиковать и на какие подписываться, а также какой сервис/посредник (EventBridge или WebSocket) необходим для публикации или подписки.
Теперь, когда наш WebSocket задокументирован, мы можем быть уверены, что его смогут использовать как внутренние команды нашей организации, так и сторонние.
Дальнейшие шаги
На этом наше путешествие по WebSocket еще не закончено. Далее мы займемся добавлением в него пользовательских уведомлений, а также собственного домена.
