M365Con 2027 – бесплатная онлайн-конференция · 11–22 Jan 2027 · 120 sessions m365con.net

API-first architecture

Concept

API-first архитектура проектирует бизнес-возможности как стабильные, вызываемые API до создания любого пользовательского интерфейса, чтобы пользовательские интерфейсы, движки рабочих процессов и ИИ-агенты использовали одни и те же операции.

✦ CONCEPTAPI-first architectureM365.FM
Title graphic: API-first architecture (Concept)

Также обсуждаются

В выпуске на тему 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.

TypeConcept
KindArchitecture

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 за шлюзом может также обслуживать клиентов-агентов наряду с веб- и мобильными клиентами.

Glossary

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: