Изучение шаблона проектирования API-First

С точки зрения карьеры я больше всего ценю две вещи: решение проблем с помощью технологий и создание технических публикаций. Первое часто приводит ко второму: результаты, представленные в публикациях, основанных на вдохновении, основаны на недавней проблеме, которую я успешно решил.

За три десятилетия своего путешествия я также обнаружил, что мне нравится составлять списки. В начале своей карьеры я использовал тетради с четырьмя линейками, чтобы составлять списки для ежедневной работы.

Конечно, эти графически оформленные потребности отошли в сторону в пользу использования производных списков, поддерживаемых в Trello или JIRA доски. Для небольших проектов я склоняюсь к использованию текстовых редакторов Sublime и Atom. Что не изменилось, так это мой предпочтительный подход к работе со списком.

Переход от списков к контурам

Для более крупных инициатив просто работа со списком не дает достаточно подробностей. Это часто случается с идеями, которые у меня есть для новой публикации.

В таких случаях я добавляю подпункты к каждому основному пункту списка. Хотя можно включить дочерние элементы на уровне подэлементов, я часто обнаруживаю, что попадаю в сорняки и не сосредотачиваюсь на более широком ландшафте.

Как только для каждого элемента в списке имеется хорошее покрытие, я выясняю, как лучше заказать каждый элемент. На этом этапе список фактически становится наброском, в котором устанавливается последовательность моих мыслей или идей.

Полученный продукт — это то, что я использовал для каждой публикации, которую я отправлял с 2015 года. Однако концепция схемы не ограничивалась моим техническим письмом. Я также использовал тот же самый подход при создании API.

API-First Design Pattern

Джанет Вагнер отметила, что в подходе, ориентированном на API, «приоритетное внимание уделяется API, поскольку многоразовые и легкодоступные продукты, потребляемые клиентскими приложениями. API-first означает разработку продуктов вокруг API с нуля, а не создание продукта и добавление API позже».

После установления стандартов API шаблон проектирования API-first выделяет время в начале процесса для создания надежного проекта API, уделяя особое внимание высокоуровневым характеристикам, в том числе: 

• Путь к ресурсу (URI)

• Типы операций/запросов (GET, PUT, POST, PATCH, DELETE)

• Входящие параметры/полезная нагрузка

• Исходящие коды ответов (1xx, 2xx, 3xx, 4xx, 5xx)

• Полезная нагрузка исходящего ответа (тип и модель данных)

• Дополнительные метаданные (описание, контакты, условия использования)

При разработке этих спецификаций я рекомендую следующий жизненный цикл:

На приведенном выше рисунке первый шаг — выслушать потребности API и повторить любые требования владельцу продукта, управляющему базовыми бизнес-правилами. После достижения этого понимания этап проектирования начинается с использования спецификации, основанной на стандартах (например, OpenAPI). Наконец, потребители API могут просмотреть его.

Часто цикл на этом не заканчивается, так как на этапе предварительного просмотра возникают вопросы и проблемы. В этот момент потребуется дополнительное время, чтобы поделиться этими опасениями с владельцем продукта, который предоставит дополнительную информацию. В этот момент начинается цикл с целью предоставления более точной спецификации API.

Используя шаблон проектирования API-first, артефакт с единственным источником достоверности документируется до написания одной строки кода. Спецификация для API будет жить вне исходных систем, создающих фактический API, таким образом, чтобы его можно было легко каталогизировать и использовать будущими инженерами по работе с клиентами и сервисными инженерами.

Теперь давайте начнем и рассмотрим простой вариант использования.

Box Finders API: пример использования

После недавнего переезда в наш новый дом я подумал о примере использования, чтобы проиллюстрировать шаблон проектирования API-first. Моя идея сосредоточена вокруг картонных коробок, используемых для перемещения вещей.

Коробки необходимы, прежде чем вы начнете собирать вещи, чтобы переехать в новый дом. Если вы похожи на меня, найти коробки, которые все еще в хорошем состоянии и за небольшую плату или бесплатно, — это идеальная ситуация. Затем, после завершения переезда, найти кого-то, кто возьмет ваши аккуратно использованные коробки, так же важно, чтобы избежать не очень привлекательной картонной витрины в углу вашего гаража.

Войдите в API Box Finders, где клиенты выполняют следующие операции:

• GET /boxes — возвращает список доступных коллекций ящиков

• GET /boxes/{id} — извлекает коллекцию из одной коробки

• POST /boxes — добавляет новую коллекцию ящиков

• PUT /boxes/{id} — обновляет существующую коллекцию ящиков

• DELETE /boxes/{id} — удаляет существующую коллекцию ящиков

Для простоты предположим, что для API Box Finders требуются следующие атрибуты:

• Id - уникальный числовой идентификатор коллекции ящиков

• Имя - имя контактного лица

• Телефон - номер телефона контакта

• Available - количество доступных ящиков

Использование Kong Insomnia с API-First Design

Поскольку я раньше не использовал приложение Kong Insomnia, я решил попробовать его для проверки шаблона проектирования API-first.

После установки начало работы с API-first дизайном начинается с использования меню Создать в левой части Kong Insomnia:

После выбора опции «Design Document» следующим шагом будет указание имени. В этом примере я ввел box-finders-spec.yaml.

В этот момент в Kong Insomnia открывается пустой проектный документ:

Теперь мы готовы приступить к разработке API Box Finders.

Добавление общей информации

В верхней части файла вы можете добавить некоторую общую информацию о спецификации. Я использовал OpenAPI версии 3.0.0:

```javascript

опенапи: 3.0.0

Информация:

версия: "0.0.1"

title: "API поиска ящиков"

Добавление информации о схеме

Основываясь на текущем понимании API Box Finders, я добавил модели данных (также известные как компоненты схемы) в конец файла:

```javascript

компоненты:

схемы:

Коробки:

тип: массив

Предметы:

$ref: "#/компоненты/схемы/коробка"

Коробка:

тип: объект

характеристики:

я бы:

тип: число

описание: Уникальный идентификатор

имя:

тип: строка

описание: Человек с коробками для раздачи

Телефон:

тип: строка

описание: Номер телефона человека с коробками для раздачи

доступный:

тип: число

описание: Количество доступных ящиков

Ошибка:

тип: объект

требуется:

• код

• сообщение

характеристики:

код:

тип: целое число

формат: int32

сообщение:

тип: строка

При таком подходе сторона данных контракта будет определена в одном центральном месте спецификации API.

Добавление URI /boxes

Имея разделы общей информации и схемы, мы можем добавить URI /boxes в качестве элементов пути в соответствии со стандартами OpenAPI:

```javascript

пути:

/ящики:

получать:

summary: "Список всех доступных коллекций ящиков"

ответы:

"200":

description: "200 ОК, все коллекции коробок"

содержание:

приложение/json:

схема:

$ref: "#/компоненты/схемы/коробки"

сообщение:

резюме: "Добавляет новую коллекцию ящиков"

тело запроса:

содержание:

приложение/json:

схема:

$ref: "#/компоненты/схемы/коробка"

требуется: правда

ответы:

«201»:

description: "201 Создано, добавлена ​​новая коллекция ящиков"

содержание:

приложение/json:

схема:

$ref: "#/компоненты/схемы/коробка"

В этом примере я добавил URI для извлечения всех коллекций ящиков и создания новой коллекции ящиков в разделе paths.

Добавление URI /boxes/{id}

**
**Далее я добавил возможность извлекать, редактировать или удалять отдельные коллекции ящиков в качестве дополнительных путей, по-прежнему следуя стандарту OpenAPI:

```javascript

/ящики/{идентификатор}:

параметры:

• в: путь

имя: идентификатор

схема:

тип: число

требуется: правда

description: "id коллекции коробок"

получать:

summary: "Получает коллекцию ящиков по идентификатору"

ответы:

"200":

description: "200 ОК, сбор ящиков по идентификатору"

содержание:

приложение/json:

схема:

$ref: "#/компоненты/схемы/коробка"

«404»:

description: "404 Not Found, коллекция ящиков не существует"

содержание:

приложение/json:

схема:

$ref: "#/компоненты/схемы/ошибка"

помещать:

сводка: "Обновляет коллекцию ящиков по идентификатору"

тело запроса:

содержание:

приложение/json:

схема:

$ref: "#/компоненты/схемы/коробка"

ответы:

«202»:

description: "202 Accepted, обновленная коллекция ящиков"

содержание:

приложение/json:

схема:

$ref: "#/компоненты/схемы/коробка"

«404»:

description: "404 Not Found, коллекция ящиков не существует"

содержание:

приложение/json:

схема:

$ref: "#/компоненты/схемы/ошибка"

удалять:

сводка: "Удаляет коллекцию ящиков по идентификатору"

ответы:

«204»:

description: "204 No Content, коллекция удаленных ящиков"

«404»:

description: "404 Not Found, коллекция ящиков не существует"

содержание:

приложение/json:

схема:

$ref: "#/компоненты/схемы/ошибка"

На данный момент версия 0.0.1 API Box Finders завершена. Однако, прежде чем двигаться дальше, я подумал, что сейчас самое время сохранить эту информацию в репозитории на основе git. Таким образом, дизайн не ограничивается существующим на моей локальной машине.

Подключение к GitHub

Клиент Kong Insomnia позволяет интегрироваться с существующим репозиторием на основе git. Я создал новый репозиторий по следующему URL-адресу:

**
**https://github.com/johnjvester/box-finders-api

Затем я создал [токен личного доступа] (https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) для создания доступа для чтения/записи к репозиторию GitHub. Затем я использовал полученный токен для настройки доступа в Kong Insomnia для спецификации API Box Finders:

На этом этапе я зафиксировал свои изменения и отправил их на GitHub. После завершения изменения из Kong Insomnia теперь доступны для других, чтобы добавить их в свой собственный клиент:

Другие, желающие просмотреть или внести свой вклад в спецификацию, могут использовать параметр Git Clone в меню Создать.

Kong Insomnia показывает полный API

С отмеченными выше изменениями Kong Insomnia показывает содержимое API:

На данный момент спецификация API Box Finders может использоваться разработчиками сервисов и потребителей без написания единой строки кода.

Использование API поиска ящиков

Для случаев, когда потребитель Box Finders API хочет разработать свое приложение, в то время как специализированная группа разрабатывает сервис Box Finders RESTful, Kong Insomnia предоставляет новому клиенту полный контракт для использования:

При выполнении GET-запроса к URI /boxes служба вернет список объектов Box:

```javascript

"идентификатор": 0,

"имя": "строка",

"телефон": "строка",

"доступно": 0

Используя шаблон проектирования «сначала API», каждый клиент или служба, привязанные к API Box Finders, могут начать свою разработку до написания одной строки кода для службы Box Finders.

Развертывание на портале разработки Kong

Если вы настроили учетную запись в Kong Konnect для использования Kong Dev Portal, вы можете использовать Параметр меню «Развернуть на портале разработки» в меню спецификации Box Finders:

Затем Kong Insomnia запросит свойства подключения перед первой попыткой развертывания:

Заключение

С прошлого года я пытаюсь жить в соответствии со следующим заявлением о миссии, которое, как мне кажется, применимо к любому ИТ-специалисту:

• «Сосредоточьте свое время на предоставлении возможностей/функциональности, которые повышают ценность вашей интеллектуальной собственности. Используйте фреймворки, продукты и услуги для всего остального».*

**
**- Дж. Вестер

В этой статье я использовал Kong Insomnia для создания стандартизированной спецификации API, которую можно полностью задокументировать, проверить и сообщить перед написанием исходного кода. Это позволяет командам совместно работать над дизайном и вносить изменения, не требуя дорогостоящих обновлений на уровне обслуживания. Ясно, что это включает в себя мою личную миссию.

Kong Insomnia — это продукт, который позволяет специализированным командам сосредоточиться на повышении ценности интеллектуальной собственности, что положительно влияет на конечный результат. Сделав шаг вперед, вы можете легко развернуть результаты Kong Insomnia на Kong Konnect, который централизует спецификации API для другие потребители, чтобы найти и использовать в своих приложениях.

В моем личном путешествии я создал списки, чтобы помочь с моими ежедневными заданиями. В большинстве случаев эти списки становились набросками, которые затем приводили к проектам и спецификациям. Шаблон проектирования API-first был для меня естественным прогрессом и, безусловно, является концепцией, которую я ценю и принимаю.

Если вас интересуют оригинальные исходные коды данной публикации, все отмеченное выше можно найти по следующей ссылке:

https://github.com/johnjvester/box-finders-api

Хорошего дня!