Процесс проектирования API
В новом проекте вам предстоит составить API для сервиса Otium, но для начала разберём, из каких шагов состоит процесс проектирования API.
Процесс проектирования API
Разработчик, архитектор ПО с более чем 25-летним стажем и консультант по API Джеймс Хиггинботэм (James Higginbotham) описал в книге «Принципы проектирования Веб-API» (Principles of Web API Design) процесс проектирования API в виде четырёх фаз и семи шагов.
Процесс проектирования API получил название ADDR, которое является аббревиатурой фаз процесса:
- Align on API Outcomes — согласовать ожидаемые результаты от реализации API между командой разработки и другими заинтересованными лицами, например, пользователями системы.
- Define Candidate APIs — определить возможные API и их функциональные возможности — операции, необходимые для достижения ожидаемых результатов реализации API.
- Design APIs — спроектировать API, в том числе выбрав его стиль: REST, SOAP или иной.
- Refine the API Design— уточнить проект API на основе информации, полученной из документации, в результате тестирования API и от заинтересованных лиц.
Фазы ADDR-процесса уточняются с помощью семи шагов:
- (Align) Определить цифровые возможности (identify digital capabilities)
- (Align) Определить действия и их шаги (capture activity steps)
- (Define) Определить границы API (identify API boundaries)
- (Define) Смоделировать профили API (model API profiles)
- (Design) Высокоуровнево спроектировать API (high-level API design)
- (Refine) Уточнить проект (refine the design)
- (Refine) Задокументировать API (document the API)
Системный аналитик участвует в процессе проектирования API, выполняя первые четыре шага ADDR-процесса.
Рассмотрим шаги ADDR-процесса на примере проектирования API маркетплейса.
Определение цифровых возможностей
Определение цифровых возможностей — это первый шаг фазы «Согласовать» (Align) ADDR-процесса.
Возможность (capability) — это способность сделать что-то. Выделяют бизнес- и цифровые возможности предприятия.
Бизнес-возможность (business capability) — это способность предприятия сделать что-то для удовлетворения бизнес-требованиям, то есть для достижения целей бизнеса и выполнения его задач. Бизнес-возможности описывают то, что делает предприятие, без описания того, как, почему или где предприятие их использует.
Например, бизнес-возможностями являются маркетинг, проектирование, производство и сопровождение продуктов.
Цифровые возможности (digital capabilities) — это средства предприятия, которые помогают ему достичь желаемых результатов с помощью автоматизации. Они предоставляют клиентам, сотрудникам и партнёрам возможность взаимодействовать с предприятием в цифровом формате.
Бизнес-возможности описывают то, чего хочет достичь предприятие, а цифровые возможности — с помощью чего оно может этого достичь.
Цифровые возможности могут принимать форму одного или нескольких технических решений и могут быть описаны на разных уровнях абстракции — начиная от целых систем и заканчивая конкретным API.
Системный аналитик определяет цифровые возможности на основе пользовательских требований. Из предыдущих спринтов вы узнали, что пользовательские требования могут быть описаны в виде вариантов использования или историй. Для определения цифровых возможностей будущего API следует использовать Job Stories.
Job Story для API
Job Stories — это первые артефакты, необходимые для согласования ожидаемых результатов от реализации API между командой разработки и другими заинтересованными лицами.
Как вы помните, шаблон Job Story состоит из трёх частей:
- Когда (ситуация),
- я хочу (мотивация),
- чтобы (ожидаемый результат).
Используемые для разработки требований к API части шаблона Job Story определяют инициирующее событие (когда), необходимую цифровую возможность (я хочу), а также ожидаемые цель или результат (чтобы).
Цифровая возможность в Job Story также должна быть сформулирована кратко, с использованием одного глагола и одного или нескольких существительных.
Системному аналитику следует помнить, что Job Stories должны быть сфокусированы на потребностях пользователей, которые API необходимо удовлетворить. На этом этапе стиль API и другие детали реализации API неважны — они будут определены в дальнейшем, в частности, на шаге высокоуровневого проектирования API.
Например, системный аналитик может написать следующую Job Story для маркетплейса:
- Когда я выбрал все нужные мне товары,
- я хочу оформить заказ,
- чтобы маркетплейс доставил заказ по указанному адресу.
В этой Job Story цифровой возможностью является оформление заказа. Эта возможность должна быть предоставлена будущим API маркетплейса, чтобы удовлетворить потребности его пользователей.
На карточке Job Story системный аналитик также записывает примечания, критерии и сценарии приёмки, которые помогают последующему тестированию API.
Определение действий и их шагов
Определив цифровые возможности, системный аналитик уточняет их с помощью действий и шагов действий. Он дополняет действия и шаги описанием и указывает выполняющих их участников — людей и системы.
Действия
Действие (activity) в контексте ADDR-процесса — это работа, необходимая для достижения ожидаемого результата.
Каждая цифровая возможность, описанная в Job Story, может состоять из одного или нескольких действий.
Действие записывают кратко, используя один глагол и одно-два существительных.
Например, цифровая возможность «Оформить заказ» может состоять из следующих действий:
- Найти товар.
- Наполнить корзину.
- Выбрать способ доставки.
- Оплатить заказ.
Системный аналитик оформляет действия в виде таблицы, записывая каждое действие в отдельной строке и указывая соответствующую цифровую возможность.
Действия необходимо дополнить информацией о людях и системах, выполняющих действие — участниках.
Каждое действие могут выполнять один или несколько участников. Они могут выполнять действие совместно или по-отдельности.
Например, выбрать способ доставки могут пользователь и менеджер маркетплейса (по запросу пользователя). При этом, оплатить заказ может только пользователь.
Шаги
Действия состоят из отдельных небольших задач — шагов действия (activity steps).
Действия могут состоять как из множества шагов, так и только из одного шага. Системному аналитику не следует беспокоиться из-за возможной разницы в количестве шагов — просто некоторые действия сложнее, чем другие.
Например, действие «Оплатить заказ» состоит из одного шага, потому что маркетплейс пользуется услугами Интернет-эквайринга, предоставляемыми платёжным агрегатором. Это значит, что маркетплейс всего лишь перенаправляет пользователя на страницу оплаты и ожидает подтверждения оплаты от платёжного агрегатора.
Шаг записывают кратко, используя один глагол и одно-два существительных.
Сначала СА следует определить все необходимые для выполнения действия шаги. Например, для действия «Наполнить корзину» СА может определить следующие шаги:
- Добавить товар в корзину.
- Изменить количество товара в корзине.
Затем, он может дополнить их другими возможными при выполнении действия шагами. Например, добавить следующие шаги для действия «Наполнить корзину»:
- Удалить товар из корзины.
- Удалить все товары из корзины.
В отличие от действия, для выполнения одного шага должен быть необходим только один участник. Если СА определил шаг, для выполнения которого необходимы несколько участников, то ему следует разделить такой шаг на несколько меньших шагов.
Если один и тот же шаг могут выполнять разные участники, но необходим только один из них, то СА можно не разбивать этот шаг на меньшие. При этом ему следует включить в описание этого шага каждого участника.
Например, ввести адрес доставки могут пользователь или менеджер, но для выполнения шага необходим только один из них.
Системный аналитик записывает каждый шаг в отдельной строке и указывает соответствующее действие.
Системный аналитик определяет действия и их шаги для каждой Job Story, описанной на предыдущем шаге ADDR-процесса. СА следует делать это совместно с заинтересованными лицами, которые разбираются в предметной области, — заказчиками, пользователями, экспертами (специалистами, у которых есть специфические знания, опыт и квалификация), владельцами продукта и бизнес-аналитиками.
СА следует фиксировать в описании действий и шагов точные термины, которые используют разбирающиеся в предметной области заинтересованные лица. Впоследствии, в программном коде API должны так же использоваться именно те названия, которые определил системный аналитик на данном этапе ADDR-процесса.
Определение границ API
Определение границ API — это первый шаг фазы «Определить» (Define) ADDR-процесса.
Границы API — это список функциональных возможностей отдельного API. Такие возможности называют операциями (operation). Операциями становятся шаги действий. Системный аналитик подробно описывает их на шаге «Моделирование профиля API» ADDR-процесса.
Целью определения границ API является группировка шагов действий на основании используемых для их записи терминов. Каждая получившаяся группа действий может быть реализована в виде отдельного API.
На данном шаге ADDR-процесса системный аналитик группирует записи таблицы действий и их шагов на основании того, как от действия к действию и от шага к шагу меняется язык их записи.
Часто, действия и шаги записываются в виде похожих по структуре предложений с использованием существительных и глаголов. СА следует обратить внимание на действия и их шаги, в которых меняются используемые существительные — именно между этими строками таблицы пролегают границы разных API.
Например, системный аналитик может обратить внимание на следующие изменение языка записи действий и их шагов (существительные выделены жирным).
После того, как границы API определены, системному аналитику следует дать им названия, которые отражают основное назначение API. Название API может отражать его функциональные возможности, результаты его работы или его целевой аудитории. Например, разные API социальной сети могут называться «Блогеры» и «Подписчики».
СА следует избегать в названии API слов «сервис» и «менеджер», потому что они не добавляют понимания назначения API.
После определения границ API и их названий системному аналитику следует разделить изначальную таблицу на несколько.
Например, для маркетплейса СА может определить API «Корзина», «Доставка» и «Оплата».
Корзина
Перед вами примеры описания шагов действий для цифровой возможности «Добавить в друзья» социальной сети. Определите к какому API относится каждый шаг.
Перетащите карточку в соответствующую колонку.
После определения границ API системный аналитик может приступить к моделированию профиля API. Как это сделать, разберём в следующем уроке.
Подведём итоги
Процесс проектирования API можно описать с помощью аббревиатуры ADDR:
- Согласовать (align) ожидаемые результаты от реализации API;
- Определить (define) функциональные возможности API (операции);
- Спроектировать (design) API;
- Уточнить (refine) проект API.
Четыре фазы уточняются с помощью семи шагов ADDR-процесса. В этом уроке вы разобрали первые три шага:
- Определить цифровые возможности Цифровые возможности — это средства предприятия, которые помогают ему достичь желаемых результатов с помощью автоматизации. Цифровой возможностью могут быть любые технические решение предприятия, например, отдельные системы, сервисы или API. Для определения цифровых возможностей будущего API системный аналитик составляет Job Stories.
- Определить действия и их шаги Определив цифровые возможности, СА уточняет их с помощью действий и шагов действий. Он дополняет действия и шаги описанием и указывает выполняющих их участников — людей и системы.
- Определить границы API Группируя действия и шаги действий СА определяет границы API. Каждая получившаяся группа действий может быть реализована в виде отдельного API.
Определив цифровые возможности, действия, шаги действий и границы API, системный аналитик может приступить к моделированию профиля API.
