Почему подход «сначала дизайн» к созданию API вызывает споры? Как победить в этом?

«Сначала дизайн» — это подход к созданию API, который требует, чтобы определение API было зафиксировано до того, как будет написан какой-либо код. На арене общественного мнения его и освистывали, и аплодировали.

В разработке продуктов API, где резина встречается с дорогой, какие препятствия мы встречаем на этом пути?

Давайте углубимся в то, как добиться успеха в подходе к API, ориентированном на проектирование.

Конструкция с фронтальной загрузкой

Для разработки в первую очередь требуется определение API, но как оно выглядит?

Определение API может иметь формат, понятный как людям, так и машинам.

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

Некоторые примеры:

• RESTful API могут использовать [Спецификацию OpenAPI] (https://www.openapis.org/)

• API-интерфейсы GraphQL используют GraphQL [язык определения схемы] (https://graphql.org/learn/schema/)

• API-интерфейсы gRPC могут использовать буферы протокола

• API на основе событий могут использовать [спецификацию AsyncAPI] (https://www.asyncapi.com/)

Ниже приведен пример того, как может выглядеть определение OpenAPI для API, помогающего потребителям находить известные цитаты:

Мы начинаем строить определение интерфейса, контракт между производителем API и потребителем API. Это служит нашим руководством для дальнейшего изучения жизненного цикла разработки программного обеспечения (SDLC). 📜

``ямл

quotable-openapi.yaml

опенапи: 3.1.0

Информация:

версия: "1.0.0"

title: Котируемый API

серверы:

• адрес: https://quotable.apilab.io

пути:

/Цитаты:

получать:

идентификатор операции: listQuotes

описание: Перечислите все известные цитаты.

ответы:

"200":

описание: хорошо

содержание:

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

схема:

$ref: "common-openapi.yaml#/components/schemas/QuoteList"

Схемы вводятся через мгновение...

Но как мы вообще до этого дойдем? См. 5 советов разработчикам по выживанию в API-First, чтобы получить некоторые идеи!

Первый дизайн

Многие преимущества рекламируются как гарантии на коробке. Давайте взглянем на некоторые из них.

Снижение затрат на разработку

Согласно [часто цитируемому исследовательскому документу] (https://www.researchgate.net/figure/IBM-System-Science-Institute-Relative-Cost-of-Fixing-Defects_fig1_255965523) института IBM System Science, исправление ошибки в тестировании в 15 раз дороже, чем исправить в дизайне. Вауза.

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

• Поддерживают ли эти API наши критерии приемки?

• Наблюдаем ли мы хорошую согласованность в каждом API?

• Каковы ограничения связи?

Простая регистрация

Потребители API бывают всех форм и размеров. Это могут быть люди, создающие приложения, которые полагаются на API. Они могут тестировать инженеров. Это могут быть даже новые сотрудники, присоединившиеся к команде разработчиков API.

• Можем ли мы получить документацию из нашего определения API?

• Можем ли мы создать клиентские SDK?

• Можем ли мы создавать активы, такие как тесты API?

Раннее управление дизайном

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

• Все ли пути на основе коллекций имеют имена во множественном числе?

• Параметры написаны в camelCase?

• Соответствуют ли названия свойств нашему вездесущему языку?

``ямл

общий-openapi.yaml

опенапи: 3.1.0

Информация:

версия: "1.0.0"

Название: Общие компоненты

пути: {}

компоненты:

схемы:

Список цитат:

тип: массив

Предметы:

$ref: "#/components/schemas/QuoteItem"

Цитата:

тип: объект

требуется:

• я бы

• содержание

• автор

• идентификатор автора

• авторSlug

• длина

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

я бы:

тип: строка

содержание:

тип: строка

автор:

тип: строка

теги:

тип: массив

Предметы:

тип: строка

идентификатор автора:

тип: строка

авторSlug:

тип: строка

длина:

тип: номер

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

OpenAPI 3.1.0 представил полную поддержку схемы JSON 2020-12.

Мы хорошие? Можем ли мы пройти?

Недостаток дизайна прежде всего

Хотя все эти преимущества кажутся хорошими и полезными, есть некоторые исторически вредные антипаттерны, вновь всплывающие на поверхность и мешающие нашим усилиям. ==Давайте осветим их пагубные намерения.== 😈

Большой дизайн впереди

Ах, да, наш старый враг, Big Design Up Front (BDUF). Такой коварный, у него глупая аббревиатура. Этот анти-шаблон пришел к нам из десятилетий следования [модели водопада] (https://en.wikipedia.org/wiki/Waterfall_model) SDLC.

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

Поток лавы

Члены команды переходят к другим проектам. Тенденции в архитектуре быстро меняются. Что происходит, когда ответственность за проектирование со временем меняется? Знание того, почему были приняты решения, часто теряется.

Когда мы не понимаем контекст, мы пытаемся внести изменения с меньшим количеством информации. Это рецепт прерывания изменений и куча инициатив по рефакторингу, которые могут никогда не завершиться.

Этот антишаблон известен как Поток лавы. Полезно знать об этом в начале любой инициативы API.

Разработка комитета

Без назначенного лица, принимающего решения, даже небольшой дизайн может занять непропорционально много времени.

В сочетании с Big Design Up Front это является важным фактором стагнации проекта.

Антишаблон Design by Committee — это неприятная ловушка, которая приводит к отставанию от графика, превышению бюджета и фрагментарности.

Заполнение выбоин

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

Достаточно дизайна для начала

Обратной стороной BDUF является то, что весь дизайн возникает из реализации, что иногда называют [Emergent Design] (https://en.wikipedia.org/wiki/Emergent_Design#Emergent_design_in_agile_software_development), хотя определения этого термина могут различаться.

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

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

Одна компромиссная философия известна как [Just Enough Design Initial (JEDI)] (http://bradapp.blogspot.com/2009/07/jedi-programming-just-enough-design.html).

«Тем не менее, мое основное эмпирическое правило, позволяющее узнать, когда достаточное моделирование было выполнено заранее, заключается в том, что после одного прохода через предполагаемый объем рассматриваемого программного обеспечения моделирование в небольших группах не создает никаких новых классов или ассоциаций реального значения. ." - Стив Палмер, [Разработка, управляемая функциями] (http://www.featuredrivendevelopment.com/node/507), 2003 г.

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

Итеративный дизайн

Если мы потратим достаточно времени в начале жизненного цикла API на размышления о дизайне, какие шаги мы можем предпринять, чтобы создать тесную петлю обратной связи?

Для API это означает:

1. Начните с проектного документа, такого как определение OpenAPI, используя инструменты, обеспечивающие совместную работу.

1. Запустите фиктивный сервер на основе этого дизайна.

1. Напишите и производителя API, и потребителя API контрактные тесты, чтобы сообщить о следующей итерации.

При необходимости, по мере продолжения разработки, такие методы, как динамическая маршрутизация через [API Gateway] (https://gateways.fyi), могут направлять клиентов либо на фиктивный сервер, либо на прототип API-сервера по мере его создания.

Эта стратегия помогает нам защитить дизайн, внося достаточно реализации, чтобы доказать, что наш дизайн действительно работает в реальном мире! 🎉

API как продукт

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

Вот несколько советов, которые помогут узаконить API как продукт:

• Дизайн всегда в приоритете.

• Назначьте менеджера по продукту API, который поможет направлять опыт, общение с заинтересованными сторонами и разработку.

• План на долголетие. Контракты, которые мы заключаем между производителем и потребителем API, требуют внимания и документации.

• Рассмотрите [Записи архитектурных решений] (https://adr.github.io/), чтобы задокументировать мотивирующие факторы и оцененные решения, помогая будущим владельцам понять, как мы сюда попали.

Дополнительная информация о том, как команды могут развиваться для удовлетворения потребностей наших продуктов API: Масштабирование команд API с помощью Platform Ops.

Масштаб вперед

На высоком уровне многие из этих концепций могут быть применены ко всей разработке программного обеспечения. Вот некоторые из преимуществ:

• Реализации API будут иметь высокий уровень согласованности.

• Будет меньше переделок после реализации.

• Дизайн и реализация более адаптивны к изменениям.

Дизайн прежде всего может потребовать больших изменений в том, как мы думаем о жизненном цикле нашего API. Помните обо всем этом, и мы в будущем будем благодарны нам. 😌

Ищете место, где можно больше поговорить о дизайне с OpenAPI? Посетите сообщество OpenAPI Discord!

Социальное фото Rick J. Brown на Unsplash

• Совместно опубликовано [здесь] (https://swiber.dev/launch-a-winning-strategy-for-api-design-first)*