API-first architecture
Concept
API-first архитектура проектирует бизнес-возможности как стабильные, вызываемые API до создания любого пользовательского интерфейса, чтобы пользовательские интерфейсы, движки рабочих процессов и ИИ-агенты использовали одни и те же операции.
Также обсуждаются
В выпуске на тему API-first architecture обсуждаются также: Computer-Using Agent (CUA), Foundry Agent Service, Service account, Agent observability, Microsoft Agent 365 и Software as a service (SaaS).
Description
API-first архитектура — это подход к проектированию, при котором бизнес-возможности определяются как стабильные, вызываемые API до того, как создаётся какой-либо пользовательский интерфейс. Затем одни и те же операции используют пользовательские интерфейсы, движки рабочих процессов и ИИ-агенты, вместо того чтобы каждый клиент обращался к логике своим собственным путём. В этой модели API рассматривается как продуктовое решение, а не как побочный результат разработки кода, поскольку внешние разработчики, партнёры и ИИ-агенты должны строить на его основе свои решения.
Ключевым элементом API-first разработки является контракт API. Согласно статье Microsoft о разработке API-first, контракт описывает эндпоинты, данные запросов и ответов, а также ожидаемые ошибки, и он пишется до реализации или пользовательского интерфейса. Контракт обычно задаётся в машиночитаемом формате, чаще всего OpenAPI. После утверждения контракта backend-команды реализуют его, а команды фронтенда и мобильных приложений разрабатывают свои части на основе моков, сгенерированных из него. Документация, SDK и тесты могут создаваться из одного и того же источника, что обеспечивает согласованность между различными артефактами.
Этот подход обычно противопоставляют code-first разработке. В схеме code-first API возникает из существующего кода, что может раскрывать внутренние детали в публичном интерфейсе. API-first меняет этот порядок: интерфейс проектируется осознанно, а код пишется так, чтобы ему соответствовать. На странице Microsoft также отмечаются компромиссы. Работа по принципу contract-first требует дополнительных усилий на проверку в начале, а подход code-first может быть разумным для раннего внутреннего инструмента, где потребителей немного и интерфейс, как ожидается, будет быстро меняться. Страница является статьёй поставщика и содержит материалы, специфичные для Azure.
Версионирование является существенной частью этой практики. Поскольку потребители зависят от контракта, версионирование рассматривается как соглашение с ними: аддитивные изменения внутри версии считаются безопасными, тогда как ломающие изменения требуют новой версии. Устаревание старых версий может сигнализироваться с помощью заголовка Sunset, что даёт потребителям определённый путь миграции вместо внезапного сбоя.
Ещё одна характеристика заключается в том, что один API может обслуживать веб-, мобильных, партнёрских клиентов и клиентов-агентов через единый шлюз. Аутентификация и ограничение частоты запросов тогда применяются единообразно ко всем вызывающим сторонам, а бизнес-логика не дублируется в отдельных каналах. Именно поэтому концепция актуальна для систем, управляемых агентами, где программным агентам нужны предсказуемые, задокументированные операции для вызова.
Эпизод M365.FM «Computer-Using Agents: How CUA Could Transform SaaS» связывает API-first архитектуру с экосистемами агентов. В эпизоде говорится, что экосистемы агентов процветают, когда принимается API-first архитектура, поскольку она позволяет связывать агентов, системы и рабочие процессы чётко и предсказуемо. В нём стабильные API описываются как основа интеллектуальных систем, а разработчики могут полагаться на них, чтобы внедрять новшества без страха перед сбоями. Также указывается на расширяемость как на преимущество, которое помогает организациям адаптироваться к меняющимся требованиям. В таком представлении API-first дизайн дополняет инвестиции в рабочие процессы, которые агенты могут создавать, автоматизировать и масштабировать.
Типичные решения, связанные с API-first архитектурой, включают выбор возможностей, которые будут открыты как API, выбор формата контракта, способы версионирования и вывода из эксплуатации изменений, а также размещение шлюза для общей аутентификации и ограничения частоты запросов. Команды также взвешивают первоначальные затраты на проверку контракта против преимуществ параллельной работы фронтенда и бэкенда, а также генерируемой документации и тестов.
Overview compiled with AI from M365.FM episodes and the facts on this page. You can improve it with the edit button below.
| Type | Concept |
|---|---|
| Kind | Architecture |
Frequently asked questions
Questions marked with AI were written with AI from the facts on this page.
Что означает API-first архитектура? (AI)
Это означает проектирование бизнес-возможностей как стабильных, вызываемых API до создания любого пользовательского интерфейса, чтобы пользовательские интерфейсы, движки рабочих процессов и ИИ-агенты все использовали одни и те же операции. Сначала определяется контракт API, а затем следует реализация.
Чем API-first отличается от code-first? (AI)
При разработке code-first API является побочным результатом существующего кода и может раскрывать внутренние детали. При разработке API-first контракт, обычно написанный на OpenAPI, проектируется и утверждается до создания реализации или пользовательского интерфейса.
Почему API-first важен для ИИ-агентов? (AI)
В эпизоде «Computer-Using Agents: How CUA Could Transform SaaS» говорится, что стабильные API составляют основу интеллектуальных систем и позволяют агентам, системам и рабочим процессам соединяться чётко и предсказуемо. Один API за шлюзом может также обслуживать клиентов-агентов наряду с веб- и мобильными клиентами.
Community wiki
Short info above, community knowledge below: add practical tips, examples or corrections. New contributions are reviewed first; trusted members publish directly.
Experts and companies for this topic
Nobody has listed this topic yet. Add it to your profile.
Maintained by Mirko Peters (Microsoft MVP) · Last updated: