Введение
Статья Майка Амундсена «7 шагов проектирования API», опубликованная в 2014 году, предлагает структурированный подход к созданию интерфейсов. Хотя за прошедшие годы инструменты и стандарты эволюционировали, некоторые принципы методологии остаются полезными. При этом ряд рекомендаций требует корректировки с учётом современных практик. Разберём ключевые этапы и их применимость в 2024 году.
1. Формирование семантических дескрипторов
Первый шаг предполагает сбор всех данных, необходимых клиентскому приложению для взаимодействия с API. Эти элементы (названия полей, статусы, параметры) формируют «словарь данных» с точки зрения клиента. Например, для сервиса управления задачами:
- id — уникальный идентификатор задачи;
- title — название задачи;
- dateDue — крайний срок выполнения;
- complete — флаг завершённости.
Критика и актуализация:
Сегодня этот этап часто интегрируется в ранние стадии проектирования через технические задания или спецификации вроде OpenAPI. Однако акцент на клиентоориентированность остаётся важным — API должно решать задачи пользователя, а не дублировать внутреннюю логику сервера.
2. Построение диаграммы состояний
Автор предлагает визуализировать переходы между состояниями данных с помощью диаграмм. Например:
- Из списка задач (GET /tasks) → в детали задачи (GET /tasks/{id});
- Из формы редактирования → в обновлённую запись (PUT /tasks/{id}).
Каждый переход помечается как безопасный (идемпотентный, например, GET) или небезопасный (изменяющий состояние, например, POST).
Замечание:
Современные подходы (например, RESTful-дизайн) уже включают подобную логику, но диаграммы состояний редко используются в явном виде. Вместо этого акцент делается на проектирование ресурсов и HTTP-методов в соответствии с семантикой REST.
3. Стандартизация терминов
Амундсен рекомендует синхронизировать названия полей с открытыми стандартами:
- id → identifier (Dublin Core);
- title → name (Schema.org);
- dateDue → scheduledTime;
- complete → status.
Контекст 2024 года:
Идея стандартизации актуальна, но выбор конкретных терминов требует осторожности. Например, status вместо complete может вводить в заблуждение (статус задачи может быть не только бинарным). Сегодня разработчики чаще придерживаются принципа ясности: названия должны быть однозначными и соответствовать предметной области, а не формально следовать внешним стандартам.
4. Выбор Media Type
На этом этапе определяется формат данных (JSON, XML) и его структура. Автор упоминает HAL или JSON:API как примеры специализированных медиа-типов.
Эволюция подхода:
Сейчас JSON доминирует, а стандарты вроде JSON:API или OpenAPI Specification (OAS) помогают унифицировать структуру ответов. Однако жёсткая привязка к узкоспециализированным форматам (например, HAL) часто избыточна — большинство проектов обходятся базовым JSON с документацией через OpenAPI.
5. Создание семантического профиля
Речь идёт о формальном описании API с использованием инструментов:
- OpenAPI/Swagger (актуальная замена упомянутого WSDL);
- AsyncAPI для event-driven архитектур;
- TypeSpec для строгой типизации.
Прогресс:
Современные генераторы кода (например, Swagger Codegen) позволяют автоматизировать создание клиентских и серверных заглушек на основе спецификации — этот этап стал рутинным в enterprise-разработке.
6. Реализация и публикация
Последние два шага — написание кода и публикация API в каталоге (например, в внутреннем реестре компании или на платформах вроде SwaggerHub).
Современная практика:
Сегодня акцент смещён в сторону документации как продукта. Помимо технических спецификаций, важно предоставлять примеры запросов, интерактивные демо (например, через Redoc) и SDK для популярных языков.
Заключение: что осталось актуальным?
Методология Амундсена 2014 года выглядит упрощённой по сравнению с сегодняшними инструментами, но её суть — проектирование API «сверху вниз» через призму потребностей клиента — остаётся фундаментальной.
Ключевые уроки для современных разработчиков:
- Начинайте с анализа данных и сценариев использования, а не с технических деталей.
- Стремитесь к предсказуемости: стандартизируйте термины и структуру ответов.
- Документируйте API как полноценный продукт, а не как техническую деталь.
Однако слепое следование устаревшим рекомендациям (например, замене dueDate на scheduledTime) может навредить. Главное — баланс между стандартами и здравым смыслом.
P.S. Даже спустя десять лет вопрос «Как проектировать API?» не имеет единого ответа. Но чем глубже вы погружаетесь в основы, тем реже попадаете в ловушку «быстрого решения», которое потом сложно исправить.