# Conceção da API - Conceber APIs que proporcionem valor

Canonical page: https://apiopscycles.com/pt/stations/api-design

Language: pt

Entity ID: api-design

## Description

Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados.

## Why it matters

Conceber APIs não se resume apenas a nomear endpoints. Um bom projeto garante que as APIs sejam utilizáveis, consistentes e alinhadas com os objetivos de negócio e técnicos. Um projeto inadequado leva a um acoplamento rígido, baixa reutilização e retrabalho dispendioso entre as equipas.

## Apply in work

Forneça padrões de projeto reutilizáveis, padrões compartilhados e ferramentas de validação para especificações de API. Garanta que as decisões de projeto sejam consistentes, revisadas antecipadamente e alinhadas com a intenção de negócios.

## Outcomes

- Conceção de API bem documentada e coerente
- Contratos de interface da API reutilizáveis e validados
- Desenhos alinhados com modelos de domínio e padrões de interação
- Rastreabilidade da conceção ao valor de negócio

## Steps

1. Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs.
2. Utilize o Canvas de Interação para definir a forma como os consumidores irão interagir com a API, garantindo que esta satisfaz as suas necessidades e expectativas.
3. Aplicar padrões de conceção REST para criar contratos de interface da API consistentes e reutilizáveis que são validados com as partes interessadas.
4. Aplicar padrões de conceção orientados para eventos para criar contratos de interface da API consistentes e reutilizáveis que são validados com as partes interessadas.
5. Aplicar padrões de conceção GraphQL para criar contratos de interface da API consistentes e reutilizáveis que são validados com as partes interessadas.
6. Utilize os princípios de projeto e o guia de estilo da API para alinhar suas decisões de projeto com regras compartilhadas e permitir uma validação de auditoria consistente.
7. Aplique abordagens do tipo ‘contrato primeiro’ ou ‘design primeiro’ para capturar e validar o contrato de interface da API antes da implementação.
8. Utilize a Lista de Verificação de Auditoria da API para garantir que a conceção da API satisfaça os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.

## Questions

- Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs.
- Utilize o Canvas de Interação para definir a forma como os consumidores irão interagir com a API, garantindo que esta satisfaz as suas necessidades e expectativas.
- Aplicar padrões de conceção REST para criar contratos de interface da API consistentes e reutilizáveis que são validados com as partes interessadas.
- Aplicar padrões de conceção orientados para eventos para criar contratos de interface da API consistentes e reutilizáveis que são validados com as partes interessadas.
- Aplicar padrões de conceção GraphQL para criar contratos de interface da API consistentes e reutilizáveis que são validados com as partes interessadas.
- Utilize os princípios de projeto e o guia de estilo da API para alinhar suas decisões de projeto com regras compartilhadas e permitir uma validação de auditoria consistente.
- Aplique abordagens do tipo ‘contrato primeiro’ ou ‘design primeiro’ para capturar e validar o contrato de interface da API antes da implementação.
- Utilize a Lista de Verificação de Auditoria da API para garantir que a conceção da API satisfaça os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.
- Forneça padrões de projeto reutilizáveis, padrões compartilhados e ferramentas de validação para especificações de API. Garanta que as decisões de projeto sejam consistentes, revisadas antecipadamente e alinhadas com a intenção de negócios.
- Conceber APIs não se resume apenas a nomear endpoints. Um bom projeto garante que as APIs sejam utilizáveis, consistentes e alinhadas com os objetivos de negócio e técnicos. Um projeto inadequado leva a um acoplamento rígido, baixa reutilização e retrabalho dispendioso entre as equipas.

## Evidence

- spec
- contract
- design-artifact
- documentation

## Completion criteria

- A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma. — The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders. (ID: architecture-patterns-validated)
- A interface selecionada fornece uma abstração adequada aos utilizadores. — The API is intended to shield consumers from backend complexity and inconsistencies. (ID: hide-backend-discrepancies)
- O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores. — The API design and exposed capabilities clearly trace back to business value and user needs. (ID: design-reflects-business-value)
- O desenho da interface segue os standards e convenções de desenho acordados. — The API design follows our shared API product and design conventions. (ID: api-consistency)

## Role participation and responsibilities

- [Arquiteto de integração](https://apiopscycles.com/pt/roles/integration-architect.md) (lead): Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.; suggested-answer-owner: [Canvas de desenho da solução de integração](https://apiopscycles.com/pt/resources/integration-solution-design-canvas.md)
- [Designer API](https://apiopscycles.com/pt/roles/api-designer.md) (lead): Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.; suggested-answer-owner: [Canvas de desenho da solução da capacidade](https://apiopscycles.com/pt/resources/capability-solution-design-canvas.md)
- [Engenheiro de automatização](https://apiopscycles.com/pt/roles/automation-engineer.md) (lead): Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.; suggested-answer-owner: [Canvas de workflow de automação](https://apiopscycles.com/pt/resources/automation-workflow-canvas.md)
- [Arquiteto de plataforma](https://apiopscycles.com/pt/roles/platform-architect.md) (core): Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.
- [Especialista de domínio](https://apiopscycles.com/pt/roles/domain-specialist.md) (core): Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.
- [Especialista em conformidade e jurídico](https://apiopscycles.com/pt/roles/compliance-specialist.md) (core): Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.
- [Especialista em segurança](https://apiopscycles.com/pt/roles/security-specialist.md) (core): Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.
- [Representante dos utilizadores da API](https://apiopscycles.com/pt/roles/api-consumer-specialist.md) (core): Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.
- [Responsável pela automatização](https://apiopscycles.com/pt/roles/automation-owner.md) (core): Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.
- [Responsável pela capacidade](https://apiopscycles.com/pt/roles/capability-owner.md) (core): Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.
- [Responsável pelo processo](https://apiopscycles.com/pt/roles/process-owner.md) (core): Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.
- [Responsável pelo produto API](https://apiopscycles.com/pt/roles/api-product-owner.md) (core): Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.
- [Engenheiro de entrega](https://apiopscycles.com/pt/roles/api-engineer.md) (consulted): Responsável pela implementação, automatização, testes e fluxo de publicação necessários para entregar a capacidade, API ou automatização de forma fiável.
- [Responsável de negócio](https://apiopscycles.com/pt/roles/business-owner.md) (consulted): Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.
- [Responsável por documentação e DevRel](https://apiopscycles.com/pt/roles/api-devrel-specialist.md) (consulted): Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.

## Cycle-specific guidance

- [Ciclo de Produto de Capacidades](https://apiopscycles.com/pt/cycles/capability-productization-cycle/stations/api-design.md)
- [Ciclo de Produto de API](https://apiopscycles.com/pt/cycles/api-productization-cycle/stations/api-design.md)
- [Ciclo de Produto de Integração](https://apiopscycles.com/pt/cycles/integration-productization-cycle/stations/api-design.md)
- [Ciclo de Automação](https://apiopscycles.com/pt/cycles/automation-cycle/stations/api-design.md)