Post #477

Никто не может объять необъятное. Сколько не изучай методы проектирования API, всегда найдется что-то новое. Или старое. Вот, например, текст, который мне раньше не попадался, и идеи, которые в нём приводятся, тоже отдельно не встречались (хотя сам я их использовал при проектировании, так часто бывает). Статья 2014 года, нужно это иметь в виду! В некоторых местах взгляды автора явно несколько устарели. Итак, Майк Амундсен, Методология проектирования API из 7 шагов, краткий пересказ: Хороший дизайн идёт прежде эндпоинтов, кодов ответов, заголовков и форматов сообщений. 1️⃣Перечислите все данные, которые клиентское приложение может захотеть получить или передать в сервис. Назовем их семантическими дескрипторами — они имеют смысл и описывают, что происходит в приложении. Важно: это точка зрения именно клиента! Примеры для приложения для ведения списка дел: id: уникальный идентификатор каждой записи в системе; title: название каждого пункта; dateDue: дата, до которой нужно сделать дело; complete: флаг да/нет, показывающий, сделано ли дело. (на курсе мы называем это "словарь данных") 2️⃣Нарисуйте диаграмму состояний Тут автор приводит некую хитрую диаграмму, где прямоугольниками нарисованы формы представления (representations) — документы или экраны, содержащие элементы данных (семантические дескрипторы из предыдущего шага). Между формами представления рисуют стрелки — переходы. То есть, каждый переход трансформирует форму представления (например, список дел➡️одно дело). Трансформации помечаются как безопасные (идемпотентные) или небезопасные (неидемпотентные). Названия переходов-трансформаций — это тоже семантические дескрипторы. 3️⃣Согласуйте "магические имена" "Магические имена" — это названия ваших семнатических дескрипторов. Майк рекомендует придумывать их не абы как, а синхронизировать с открытыми перечнями названий данных и операций: schema.org, microformats.org, Dublin Core, IANA Link Relation Values. Идея в том, что с этими именами разработчики клиентов могли ранее сталкиваться в других API, и поймут их смысл. Для своего примера он выбирает такие названия: id -> identifier из Dublin Core; title -> name из Schema.org; dueDate -> scheduledTime(мне кажется, dueDate было понятнее) complete -> status (вот тут я против, скажу прямо) (В общем, спорное решение, но вообще над стандартизацией названий и действий стоит задуматься!) 4️⃣Выберите Media Type Тут можно выбирать между XML/HTML/JSON/и т.д., но можно и глубже — например, структуры JSON могут быть разными (скажем, есть HAL, а есть JSON:API, это всё зарегистрированные IANA медиа-типы). 5️⃣Создайте "семантический профиль" Тут всё просто — это OpenAPI или TypeSpec (автор упоминает WSDL, я немного актуализировал). 6️⃣Напишите или сгенерируйте серверный и клиентский код. 7️⃣Опубликуйте описание API в каталоге (Имеется в виду, что он есть у вас в организации или вы публикуете спецификацию открытого API в одном из общедоступных каталогов). Вот такие шаги :) С одной стороны, сейчас звучит немного наивно, с другой — если задуматься, то часто ли мы делаем эти шаги и вообще задумываемся об этих вещах? Нам бы с эндпоинтами и кодами ошибок разобраться...