Моделирование профиля API
В прошлом уроке вы узнали о шагах, которые нужно выполнить для проектирования API, и разобрали первые три шага. В этом уроке вы узнаете о последних четырёх шагах ADDR-процесса.
Моделирование профиля API
На этом этапе ADDR-процесса системный аналитик составляет модель API, которая называется профилем API (API profile), и описывает функциональные возможности API — операции.
Профиль API позволяет уточнить ожидания команды разработки и заинтересованных лиц от API и достичь одинакового их понимания.
Для моделирования профиля API системный аналитик использует Job Stories и действия как входные данные. В результате моделирования API системный аналитик может составить один или несколько профилей API.
Профиль API состоит из следующих элементов:
- Название API.
- Краткое описание.
- Вид API.
- Название операции.
- Краткое описание операции.
- Участники, которым доступно выполнение операции.
- Используемые для выполнения операции ресурсы.
- Детали операции.
Процесс моделирования профиля проходит в четыре шага:
- Добавить основную информацию.
- Определить ресурсы.
- Определить таксономию ресурсов.
- Добавить детали операций.
Также системному аналитику нужно проверить описанную в профиле модель API с помощью диаграммы последовательности.
Шаг 1. Добавить основную информацию
Системный аналитик определяет и записывает:
- Название API.
- Краткое описание API.
- Вид API.
Название API в профиле соответствует тому названию, которое было определено на шаге «Определение границ API» ADDR-процесса. Например, «Корзина», «Доставка», «Оплата».
Краткое описание API — это любая важная информация об API. Например, «Позволяет наполнить корзину товарами для оформления заказа».
Вид API может ограничивать технические решения, которые принимают команды разработки для реализации API. Выделяют такие виды API:
- Внутренний API (internal API) соединяет программы, разработанные одним и тем же предприятием. Люди и программы вне предприятия не могут просматривать и использовать внутренние API.
- Публичный API (public API) соединяет программы, разработанные разными предприятиями. Публичные API доступны для просмотра и использования людьми и программами по всему миру. Например, все предприятия, пользующиеся услугами Почты России, могут с помощью его API получать текущий статус по всем отправлениям, детальную историю перемещений отправлений и другую информацию.
- Партнёрский API (partner API) также соединяет программы, разработанные разными предприятиями, и доступен для просмотра кому угодно. При этом API недоступен для использования без согласия разработчика. Например, партнёрский API ЮMoney может просматривать кто угодно, но использовать его — только после заключения договора с разработчиком API.
Выберите из выпадающего списка вид API, соответствующий описанию.
Образовательный портал опубликовал API для своих студентов и всех желающих. Любой человек может бесплатно подключиться к API, изучить его и протестировать его работу.
Публичный
Публичный API позволяет людям и программам других компаний бесплатно использовать функциональные возможности.
Приложение для формирования бухгалтерских проводок использует API приложения для учёта платёжных поручений. Оба приложения принадлежат одному и тому же банку.
Внутренний
Внутренний API могут использовать только другие программы того же предприятия, потому что он передаёт данные, представляющие собой коммерческую тайну.
Приложение для чтения электронных книг бесплатно использует API приложения для прослушивания музыки, разработанного другой компанией.
Компании договорились, что использование API выгодно обеим: для одой компании это повышение удовлетворённости пользователей, а для другой — реклама.
Партнёрский
Партнёрский API недоступен для использования без согласия его разработчика. Соглашение между потребителем и разработчиком API не всегда предполагает взимание платы за использование API.
После названия, описания и вида API системный аналитик определяет перечень операций API и записывает для каждой из них:
- Название.
- Краткое описание.
- Участников, которым доступно выполнение операции.
Перечень операций соответствует шагам действий Job Stories.
Название операции представляет собой название шага действия, записанного в формате camelCase. Например, шаг «Добавить товар» может быть записан как «добавитьТовар». В конце названия нужно добавить пустые скобки: «добавитьТовар()».
Краткое описание операции полностью соответствует описанию шага.
Участники, которым доступно выполнение операций, также полностью совпадают с участниками, выполняющими шаги действий.
Системный аналитик оформляет профиль API в виде таблицы, записывая каждую операцию в отдельной строке.
Рассмотрим на примере маркетплейса, как получившееся на шаге «Определение границ API» описание действий и их шагов преобразуется в профиль API.
Таблица из шага «Определение границ API»:
Корзина
Шаг 2. Определить ресурсы
На этом шаге системный аналитик определяет ресурсы (resource) API, используемые для выполнения операций.
Чтобы определить ресурсы, нужно обратить внимание на существительные в названии операции — именно они и являются ресурсами.
Например, в названии каждого шага действия «Наполнить корзину» встречается сочетание слов «товар» и «корзина». Товар в корзине — это ресурс.
Если использовать только слово «товар» без «корзины», это может вызвать путаницу. Представьте, что разработчики реализуют операцию API «удалитьВсеТовары()» для ресурса «товар» — это значит, что при выполнении этой операции могут быть удалены все товары маркетплейса, а не только товары в корзине конкретного пользователя.
Также можно отдельно добавить ресурс «Корзина», который будет хранить данные об общей стоимости товаров в корзине с учётом количества единиц.
Для записи названий ресурсов СА требуется фиксировать в описании действий и шагов точные термины, которые используют разбирающиеся в предметной области заинтересованные лица.
Бывает непросто определить ресурсы, которые не изменятся в дальнейшем — во время проектирования API и уточнения его ADDR-процесса. Но эта работа важна, поскольку команда разработки будет опираться на определённые системным аналитиком ресурсы.
Итак, ресурсами API «Корзина» будут «Товар в корзине» и «Корзина».
Таблица «Профиль API»
Название: Корзина
Краткое описание API: Позволяет наполнить корзину товарами для оформления заказа
Вид API: Внутренний API
Свойства ресурса
Ещё системный аналитик определяет уже известные ему свойства (property) каждого ресурса. Состав свойств не должен быть избыточным — СА следует описывать только те свойства, которые необходимы для выполнения операций.
В дальнейшем свойства ресурсов станут основной для параметров запросов к API. Но на этом шаге ADDR-процесса СА не должен задумываться о реализации свойств ресурса — стоит сфокусироваться на используемых в названии и описании свойств терминах.
Несмотря на отсутствие деталей реализации, определение свойств ресурса — непростая задача. Дело в том, что СА может описать свойства ресурса так же, как описывал бы модель сущностей и связей. Но моделирование свойств ресурсов и атрибутов сущностей различается.
Системный аналитик оформляет свойства ресурса API в виде таблицы, записывая каждое свойство в отдельной строке. Таблица содержит название ресурса, свойства и их описание.
Корзина
Товар в корзине
Шаг 3. Определить таксономию ресурсов
После определения ресурсов API и их свойств системный аналитик описывает связи между ними — таксономию (taxonomy) API. Таксономия — это классификация и организация понятий. А таксономия API — это ресурсы API и их связи.
Есть три вида связей между ресурсами API:
- Независимая (independent) Один ресурс может существовать вне зависимости от другого ресурса. Он может быть связан с другими зависимыми или независимыми ресурсами. Например, таким ресурсом будет «Товар», потому что его существование не зависит от корзины или товара в корзине.
- Зависимая (dependent) Один ресурс не может существовать без другого — родительского ресурса. Зависимые ресурсы встречаются достаточно редко. Например, таким ресурсом будет «Корзина» — она не будет существовать, пока не существует ресурса «Товар в корзине». Пустая корзина, которая обычно видна пользователю маркетплейса, — это ещё не ресурс, а всего лишь элемент интерфейса. До того, как в неё будет добавлен хотя бы один товар, нет смысла создавать ресурс корзины пользователя.
- Ассоциирующая (associative) Ресурсы могут существовать независимо друг от друга, но их связь требует дополнительного свойства для её описания. В результате появляется третий ресурс, представляющий собой связь между этими двумя. Третий ресурс может быть связан с двумя другими зависимой или независимой связью. Например, третьим ресурсом будет «Товар в корзине» — он описывает связь между ресурсами «Товар» и «Корзина». «Товар» и «Корзина» будут связаны друг с другом ассоциирующей связью, а с «Товаром в корзине» — другими видами связей.
Системный аналитик описывает таксономию ресурсов в виде таблиц, соединённых именованными (подписанными) стрелками. За исключением подписей, все стрелки имеют одинаковый вид. Каждая таблица содержит название ресурса, свойства и их описание.
Перед вами диаграмма, описывающая таксономию ресурсов API для прослушивания музыкальных треков и составления пользователями индивидуальных плейлистов.
Выберите из выпадающего списка вид связи, соответствующий её номеру на диаграмме.
1
Независимая
Связь независимая, когда один ресурс может существовать вне зависимости от существования другого ресурса. Данные об исполнителе музыкального трека могут быть представлены в API вне зависимости от того, разместил ли исполнитель хотя бы один трек.
2
Независимая
Трек может существовать вне зависимости от того, добавил ли его кто-то из пользователей в свой индивидуальный плейлист.
3
Зависимая
Связь зависимая, когда один ресурс не может существовать без существования другого — родительского ресурса. Существование плейлиста бессмысленно без хотя бы одного добавленного трека.
4
Ассоциирующая
Связь ассоциирующая, когда ресурсы могут существовать вне зависимости друг от друга, но их связь требует дополнительного свойства для её описания. Плейлист и трек связаны треком в плейлисте.
Шаг 4. Добавить детали операций
Завершающий шаг процесса моделирования профиля — добавление деталей операций.
К деталям операций относятся:
- Запрашиваемые (входные) и возвращаемые (выходные) ресурсы.
- Параметры запроса.
- Безопасность и идемпотентность.
- Синхронность или асинхронность.
Не стремитесь описывать абсолютно все ресурсы и параметры — нужно зафиксировать только самые необходимые. Важна не полнота описания, а единое понимание командой разработки и другими заинтересованными лицами цели операции.
Полное описание ресурсов и параметров будет составлено во время проектирования API.
Вот порядок действий:
- Записать запрашиваемые (входные) и возвращаемые (выходные) ресурсы.
- Записать параметры запроса. Они так же, как и операции, записываются в формате camelCase, но добавлять пустые скобки в конце не нужно.
- Указать безопасность и идемпотентность. Вы познакомились с безопасностью методов и их идемпотентностью в уроке «HTTP-запрос».
- Указать синхронность или асинхронность операции. Эта информация может влиять на технические решения, принимаемые при разработке API. В частности, синхронное API использует для взаимодействия запросы и ответы, тогда как асинхронное предоставляет результат через некоторое время, выполняя скрытую от потребителя API работу.
Корзина — Позволяет наполнить корзину товарами для оформления заказа
Внутренний API
На последующих шагах ADDR-процесса системному аналитику может понадобиться внести изменения в профиль API. Не стоит из-за этого беспокоиться, потому что разработке ПО и API сопутствует высокий уровень неопределённости. По мере того как команда разработки будет узнавать больше подробностей об ожидаемых от реализации API результатах и об используемых технологиях, она будет неоднократно просить СА скорректировать описание модели API в профиле.
Высокоуровневое проектирование API
Высокоуровневое проектирование API — это первый и единственный шаг фазы «Спроектировать» (Design) ADDR-процесса. Это проектирование высокоуровневое, потому что за ним следует шаг уточнения проекта.
Получив от системного аналитика модель API, описанную в профиле, команда разработки приступает к высокоуровневому проектированию API. В процессе проектирования члены команды принимают множество технических решений. Например, они выбирают стиль API, протоколы, стиль представления данных и другие технологии.
Чаще всего команде не удаётся с первого раза принять оптимальные решения, поэтому они разрабатывают прототип API для проверки технических гипотез и получения обратной связи от заинтересованных лиц.
Результатом этого шага будет проект API.
Уточнение проекта
Уточнение проекта — это первый шаг фазы «Уточнить» (Define) ADDR-процесса. Цель фазы «Уточнить» — усовершенствование проекта API и подготовка к поставке будущего API.
На протяжении ADDR-процесса были определены цифровые возможности, смоделирован профиль API и спроектирован с учётом определённых технологий высокоуровневый проект API. Теперь команда разработки сосредоточится на повышении критериев качества API, определении стратегий тестирования API и выборе формата документации API.
Результатом этого шага будут уточнённый проект API и другая документация, например описывающая порядок его тестирования.
Документирование API
ADDR-процесс проектирования API завершается документированием API.
Традиционно техническая документация распространяется в файлах форматов MS Word, PDF или других — такую документацию могут использовать только люди.
Техническая документация API распространяется в машиночитаемом формате (machine-readable format). Это значит, что использовать её могут программы. При этом специальные инструменты генерируют такую документацию на основе подготовленного людьми описания.
Готовят документацию API разработчики. Они определяют формат документации и описывают в ней все технические решения, принятые в ADDR-процессе.
К популярным форматам документации API относятся:
- Спецификация OpenAPI (ранее называлась Swagger) Это один из самых популярных форматов описания REST API. Спецификация OpenAPI стала популярной благодаря возможности отправить запрос и получить ответ через веб-приложение — Swagger UI. Эта функция позволяет как разработчикам, так и любым другим заинтересованным лицам гораздо проще изучить операции API. Вы можете ознакомиться с этой функцией на примере Swagger Petstore. Раскройте любую из операций API и нажмите на кнопку Try it out.
- API Blueprint Описывает API c помощью облегчённого языка разметки — Markdown — и дополняется особой структурой, которая делает описание машиночитаемым и позволяет автоматически генерировать программный код.
- Язык моделирования RESTful API (RESTful API Modeling Language — RAML) Описывает ресурсы, методы, параметры, ответы и другие элементы протокола HTTP, используемые в REST API. При этом RAML может описывать любые стили API, основанные на протоколе HTTP.
- JSON-схема Может быть использована для описания представлений ресурсов для REST API и других стилей.
После того как ADDR-процесс завершается, команда разработки приступает к реализации API.
Подведём итоги
В этом уроке вы разобрали последние четыре шага ADDR-процесса:
- Смоделировать профили API Системный аналитик составляет модель API, которая называется профилем API, и описывает функциональные возможности — операции. Он также определяет ресурсы API и их таксономию. После моделирования профиля API системный аналитик проверяет модель API с помощью диаграммы последовательности.
- Высокоуровнево спроектировать API Члены команды разработки принимают множество технических решений и описывают их в проекте API. Они также разрабатывают прототип API для проверки технических гипотез и получения обратной связи от заинтересованных лиц.
- Уточнить проект Члены команды разработки уточняют проект API и разрабатывают другую документацию, необходимую для реализации, тестирования и поставки API.
- Задокументировать API Члены команды разработки определяют формат документации API и описывают в ней все технические решения, принятые в ADDR-процессе.
После того как ADDR-процесс завершается, команда разработки приступает к реализации API.
