API-first architecture
Concept
A arquitetura API-first projeta as capacidades de negócio como APIs estáveis e acessíveis antes de qualquer interface de usuário, de modo que interfaces de usuário, mecanismos de fluxo de trabalho e agentes de IA consumam as mesmas operações.
Também abordados
O episódio sobre API-first architecture aborda também Computer-Using Agent (CUA), Foundry Agent Service, Service account, Agent observability, Microsoft Agent 365 e Software as a service (SaaS).
Descrição
A arquitetura API-first é uma abordagem de design na qual as capacidades de negócio são definidas como APIs estáveis e acessíveis antes que qualquer interface de usuário seja construída. As mesmas operações são então consumidas por interfaces de usuário, mecanismos de fluxo de trabalho e agentes de IA, em vez de cada cliente acessar a lógica por um caminho próprio. Nesse modelo, a API é tratada como uma decisão de produto, e não como um subproduto do código, porque desenvolvedores externos, parceiros e agentes de IA devem poder construir sobre ela.
Um elemento central do desenvolvimento API-first é o contrato da API. De acordo com o artigo da Microsoft sobre desenvolvimento API-first, o contrato descreve os endpoints, os dados de requisição e resposta e os erros esperados, e é escrito antes da implementação ou da interface de usuário. O contrato geralmente é expresso em um formato legível por máquina, mais comumente OpenAPI. Depois que o contrato é aprovado, as equipes de backend o implementam, enquanto as equipes de front-end e mobile desenvolvem com base em mocks gerados a partir dele. Documentação, SDKs e testes podem ser gerados a partir da mesma fonte, o que mantém os diferentes artefatos consistentes entre si.
A abordagem costuma ser contrastada com o desenvolvimento code-first. Em uma configuração code-first, a API surge do código existente, o que pode expor detalhes internos na interface pública. O API-first inverte essa ordem: a interface é projetada deliberadamente, e o código é escrito para atendê-la. A página da Microsoft também menciona compensações. O trabalho contract-first exige esforço de revisão antecipado, e uma abordagem code-first pode ser razoável para uma ferramenta interna inicial, em que os consumidores são poucos e a interface deve mudar rapidamente. A página é um artigo de fornecedor e contém conteúdo específico do Azure.
O versionamento é uma parte significativa da prática. Como os consumidores dependem do contrato, o versionamento é tratado como um acordo com eles: alterações aditivas são consideradas seguras dentro de uma versão, enquanto alterações que quebram a compatibilidade exigem uma nova versão. A descontinuação de versões antigas pode ser sinalizada com um cabeçalho Sunset, oferecendo aos consumidores um caminho definido para migrar, em vez de uma interrupção abrupta.
Outra característica é que uma única API pode atender clientes web, mobile, parceiros e agentes por trás de um único gateway. Autenticação e limitação de taxa então se aplicam uniformemente a todos os chamadores, e a lógica de negócio não é duplicada em canais separados. Essa é a razão pela qual o conceito é relevante para sistemas orientados a agentes, nos quais agentes de software precisam de operações previsíveis e documentadas para chamar.
O episódio do M365.FM "Computer-Using Agents: How CUA Could Transform SaaS" conecta a arquitetura API-first aos ecossistemas de agentes. O episódio afirma que os ecossistemas de agentes prosperam quando uma arquitetura API-first é adotada, porque permite conectar agentes, sistemas e fluxos de trabalho com clareza e previsibilidade. Ele descreve as APIs estáveis como a espinha dorsal de sistemas inteligentes e afirma que os desenvolvedores podem contar com elas para inovar sem temer interrupções. Também aponta a extensibilidade como um benefício, ajudando as organizações a se adaptarem a requisitos em evolução. Nessa perspectiva, o design API-first se soma ao investimento em fluxos de trabalho que os agentes podem criar, automatizar e escalar.
Decisões típicas em torno da arquitetura API-first incluem quais capacidades expor como APIs, qual formato de contrato usar, como versionar e descontinuar alterações e onde posicionar um gateway para autenticação e limitação de taxa compartilhadas. As equipes também avaliam o custo antecipado da revisão de contratos contra os benefícios do trabalho paralelo de front-end e backend e da documentação e dos testes gerados.
Overview compiled with AI from M365.FM episodes and the facts on this page. You can improve it with the edit button below.
| Tipo | Concept |
|---|---|
| Kind | Architecture |
Perguntas frequentes
Questions marked with AI were written with AI from the facts on this page.
O que significa arquitetura API-first? (AI)
Significa projetar as capacidades de negócio como APIs estáveis e acessíveis antes de qualquer interface de usuário, de modo que interfaces de usuário, mecanismos de fluxo de trabalho e agentes de IA consumam todos as mesmas operações. O contrato da API é definido primeiro e a implementação vem depois.
Em que o API-first difere do code-first? (AI)
No desenvolvimento code-first, a API é um subproduto do código existente e pode expor detalhes internos. No desenvolvimento API-first, o contrato, geralmente escrito em OpenAPI, é projetado e aprovado antes de a implementação ou a interface de usuário serem construídas.
Por que o API-first é relevante para agentes de IA? (AI)
O episódio "Computer-Using Agents: How CUA Could Transform SaaS" afirma que APIs estáveis formam a espinha dorsal de sistemas inteligentes e permitem que agentes, sistemas e fluxos de trabalho se conectem com clareza e previsibilidade. Uma única API por trás de um gateway também pode atender clientes de agentes ao lado de clientes web e mobile.
Community wiki
Short info above, community knowledge below: add practical tips, examples or corrections. New contributions are reviewed first; trusted members publish directly.
Especialistas e empresas para este tópico
Ninguém indicou ainda este tópico. Adicione-o ao seu perfil.
Maintained by Mirko Peters (Microsoft MVP) · Last updated: