Проектирование API для пользователей. Определение целей API.

Таблица целей API (рис. 2.14) состоит из шести столбцов, соответствующих процессу, который мы обнаружили в предыдущих разделах: ➖Кто – здесь вы перечисляете пользователей API (или профили); ➖Что – здесь вы перечисляете, что могут делать эти пользователи; ➖Как – здесь вы разбиваете каждое действие на этапы; ➖Входные данные (источник) – здесь вы перечисляете, что необходимо для каждого шага и откуда это берется (чтобы определить недостающих пользователей, действия или способы их реализации); ➖Выходные данные (использование) – здесь вы перечисляете, что возвращает каждый этап и как это используется (чтобы определить недостающих пользователей, действия или способы их реализации); ➖Цели – здесь вы четко и кратко переформулируете каждый способ реализации + входные данные + выходные данные.

На рис. 2.15 показано частичное представление таблицы целей нашего API онлайн-магазина. Таблица целей API и лежащий в ее основе метод опроса помогут вам представить, кто использует API, что они могут с ним делать, как они это делают, что им нужно и что они получают взамен. Это фундаментальная информация, необходимая для проектирования программного интерфейса, представляющего определенные цели. Вы, возможно, заметили, что мы не говорили о мелкоструктурных данных и ошибках. Мы поговорим о них позже ). Таблица целей API – это только высокоуровневое представление; на этом этапе не следует слишком углубляться в детали.

Имейте в виду, что, даже не вдаваясь в такие подробности, наполнение целей API может быть довольно сложным в сложных контекстах. Пользователей или профилей может быть много или слишком много вариантов использования. Это не ограничивается проектированием API и происходит при проектировании любого программного решения. Не пытайтесь охватить все случаи использования одним выстрелом. Вместо этого сфокусируйтесь на небольшом наборе вариантов. Если действие содержит множество этапов или ответвлений, сосредоточьтесь на главном пути, а после этого проверьте, есть ли изменения, приводящие к появлению новых целей в других путях. То же самое касается пользователей: попытка изучить все действия для всех пользователей или профилей может быть непростой. Сосредоточьтесь на основном пользователе или профиле и после этого проверьте, если есть варианты для других.

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

ПРИМЕЧАНИЕ. Не стесняйтесь адаптировать этот метод и инструмент или использовать любой другой метод, с которым вы знакомы, при условии, что он позволяет вам получать информацию, перечисленную в таблице целей API. Книга: Проектирование веб-API, автор: Арно Лоре.