{ "source": { "repository": "https://github.com/APIOpsCycles/apiops-cycles-method-data", "commit": "4418d7ccff492f591957f0e53fd9d476354041d7" }, "locales": [ "en", "fi", "fr", "de", "pt" ], "defaultLocale": "en", "generatedAt": "2026-07-24T13:03:14.377Z", "translations": { "pt": { "labels": { "stations": "Estações", "why_it_matters": "Porque existe esta estação?", "outcomes": "Resultados", "how_it_works": "Como funciona", "steps": "Passos", "apply_in_work": "Como é o sucesso na prática", "related_metrolines": "Incluído nestas linhas", "entry_criteria_title": "Sinais de partida", "exit_criteria_title": "Concluído com qualidade quando", "cycles.title": "Vistas de ciclo", "cycles.description": "Vistas específicas por público sobre o método APIOps Cycles", "cycle.capability-productization-cycle.title": "Ciclo de Produto de Capacidades", "cycle.capability-productization-cycle.description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação.", "cycle.capability-productization-cycle.purpose": "Identificar e transformar capacidades digitais reutilizaveis em produto antes de escolher um estilo de implementacao API, evento, ficheiro, stream, produto de dados, servico com IA, integracao direta ou hibrido.", "cycle.api-productization-cycle.title": "Ciclo de Produto de API", "cycle.api-productization-cycle.description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las.", "cycle.api-productization-cycle.purpose": "Jornada do metodo focada em API para equipas que ja sabem que o estilo de implementacao pretendido e um produto API.", "cycle.integration-productization-cycle.title": "Ciclo de Produto de Integração", "cycle.integration-productization-cycle.description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao.", "cycle.integration-productization-cycle.purpose": "Orientar a concecao de capacidades de integracao reutilizaveis antes de escolher um estilo de implementacao API, evento, ficheiro, stream, produto de dados, integracao direta ou hibrido.", "cycle.station.capability-strategy": "Estrategia da capacidade", "cycle.station.consumer-requirements-onboarding": "Requisitos e onboarding de utilizadores", "cycle.station.architecture-platform-decisions": "Decisões de arquitetura e plataforma", "cycle.station.solution-interface-design": "Conceção da solução e da interface", "cycle.station.delivery-operations": "Entrega e operações", "cycle.station.quality-readiness-assurance": "Garantia de qualidade e prontidão", "cycle.station.publishing-enablement": "Publicacao e enablement", "cycle.station.monitoring-improvement": "Monitorização e melhoria", "cycle.station.api-product-strategy": "Estratégia de produto API", "cycle.station.api-consumer-experience": "Experiência do consumidor da API", "cycle.station.api-platform-architecture": "Arquitetura da plataforma API", "cycle.station.api-design": "Conceção da API", "cycle.station.api-delivery": "Entrega da API", "cycle.station.api-audit": "Auditoria da API", "cycle.station.api-publishing": "Publicação da API", "cycle.station.monitoring-and-improving": "Monitorizacao e melhoria da API", "cycle.station.integration-capability-strategy": "Estratégia da capacidade de integração", "cycle.station.integration-consumer-requirements-onboarding": "Requisitos e integração de consumidores da integração", "cycle.station.integration-architecture-decision": "Arquitetura de integracao e decisoes de plataforma", "cycle.station.integration-solution-design": "Conceção da solução de integração", "cycle.station.integration-delivery-operations": "Entrega e operações da integração", "cycle.station.integration-readiness-assurance": "Garantia de prontidão da integração", "cycle.station.capability-publishing": "Publicacao e enablement da integracao", "cycle.station.integration-monitoring-improvement": "Monitorização e melhoria da integração", "cycle.capability-productization-cycle.station.api-product-strategy.description": "Antes de construir qualquer coisa, defina o valor, os consumidores, a propriedade e os objetivos de negócio da capacidade.", "cycle.capability-productization-cycle.station.api-consumer-experience.description": "Recolha requisitos de integração dos consumidores, normas, requisitos não funcionais, expectativas de serviço, restrições, necessidades de segurança, protocolos permitidos, atualidade dos dados, SLAs, observabilidade, recuperação, requisitos de adoção e responsabilidades dos produtores.", "cycle.capability-productization-cycle.station.api-platform-architecture.description": "Utilize requisitos e restrições para decidir o padrão de arquitetura certo e as capacidades de plataforma de suporte.", "cycle.capability-productization-cycle.station.api-design.description": "Conceba o contrato de interface e o modelo de interação para o estilo de disponibilização selecionado.", "cycle.capability-productization-cycle.station.api-delivery.description": "Construa, teste, disponibilize e opere a capacidade usando o estilo de disponibilização selecionado e o contrato de interface validado.", "cycle.capability-productization-cycle.station.api-audit.description": "Audite o contrato de interface, os controlos, o modelo de suporte, a observabilidade, a documentação e a prontidão de ciclo de vida da capacidade antes da disponibilização.", "cycle.capability-productization-cycle.station.api-publishing.description": "Publique informação sobre a capacidade reutilizável para que os consumidores a possam descobrir, solicitar, integrar, utilizar e obter suporte.", "cycle.capability-productization-cycle.station.monitoring-and-improving.description": "Monitorize a utilização, fiabilidade, qualidade dos dados, resultados dos consumidores, custo operacional e oportunidades de reutilização após a disponibilização.", "cycle.owner.business-owner": "Responsável de negócio", "cycle.owner.domain-expert": "Especialista de domínio", "cycle.owner.capability-owner": "Responsável pela capacidade", "cycle.owner.consumer-representative": "Representante dos consumidores", "cycle.owner.enterprise-architect": "Arquiteto empresarial", "cycle.owner.platform-owner": "Responsável pela plataforma", "cycle.owner.api-product-owner": "Responsável pelo produto API", "cycle.owner.api-platform-owner": "Responsável pela plataforma API", "cycle.owner.integration-architect": "Arquiteto de integração", "cycle.owner.solution-architect": "Arquiteto de solução", "cycle.api-productization-cycle.station.api-product-strategy.description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia.", "cycle.api-productization-cycle.station.api-consumer-experience.description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento.", "cycle.api-productization-cycle.station.api-platform-architecture.description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma.", "cycle.api-productization-cycle.station.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.", "cycle.api-productization-cycle.station.api-delivery.description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia.", "cycle.api-productization-cycle.station.api-audit.description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição.", "cycle.api-productization-cycle.station.api-publishing.description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos.", "cycle.api-productization-cycle.station.monitoring-and-improving.description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua.", "cycle.integration-productization-cycle.station.api-product-strategy.description": "Enquadrar a capacidade de integracao reutilizavel, a necessidade de negocio, o ownership e a reutilizacao esperada antes de selecionar o estilo de implementacao.", "cycle.integration-productization-cycle.station.api-consumer-experience.description": "Recolha consumidores da integração, responsabilidades dos fornecedores, necessidades de integração, expectativas de serviço e restrições operacionais.", "cycle.integration-productization-cycle.station.api-platform-architecture.description": "Selecionar a arquitetura de integracao, o estilo de implementacao e as capacidades de plataforma, tendo em conta as restricoes e o modelo de governacao.", "cycle.integration-productization-cycle.station.api-design.description": "Conceber o contrato de interface, os esquemas, os payloads e os padroes de interacao para o estilo de integracao selecionado.", "cycle.integration-productization-cycle.station.api-delivery.description": "Construir, testar, automatizar, disponibilizar e operar a capacidade de integracao usando o estilo de implementacao selecionado e o contrato de interface validado.", "cycle.integration-productization-cycle.station.api-audit.description": "Assegure a prontidão, a governação, a qualidade, a segurança, a conformidade e as evidências operacionais da integração antes da disponibilização.", "cycle.integration-productization-cycle.station.api-publishing.description": "Publicar a capacidade de integracao para que as equipas a possam descobrir, avaliar, solicitar acesso, concluir o onboarding, reutiliza-la e obter suporte.", "cycle.integration-productization-cycle.station.monitoring-and-improving.description": "Monitorize a fiabilidade da integração, a reutilização, os incidentes, o desempenho, os resultados dos consumidores e as necessidades de melhoria.", "cycle.automation-cycle.title": "Ciclo de Automação", "cycle.automation-cycle.description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação.", "cycle.automation-cycle.purpose": "Transformar oportunidades de automação em fluxos de trabalho governados com utilizadores, plataformas, controlos, percursos de entrega, capacitação e monitorização claros.", "cycle.audience.automation-owners": "Responsáveis pela automação", "cycle.audience.process-owners": "Responsáveis pelo processo", "cycle.audience.automation-teams": "Equipas de automação", "cycle.station.automation-opportunity-strategy": "Estratégia da oportunidade de automação", "cycle.station.process-user-requirements": "Requisitos do processo e dos utilizadores", "cycle.station.automation-platform-decision": "Decisão de plataforma de automação", "cycle.station.automation-workflow-design": "Conceção do fluxo de trabalho de automação", "cycle.station.automation-delivery": "Entrega e operacao da automacao", "cycle.station.automation-readiness-review": "Revisão de prontidão da automação", "cycle.station.automation-enablement": "Rollout e enablement da automacao", "cycle.station.automation-monitoring-improvement": "Monitorização e melhoria da automação", "cycle.automation-cycle.station.api-product-strategy.description": "Identifique e priorize oportunidades de automação por valor, viabilidade, risco, propriedade e impacto esperado no processo.", "cycle.automation-cycle.station.api-consumer-experience.description": "Recolha utilizadores do processo, funções, transferências, exceções, restrições e expectativas de serviço antes de conceber a automação.", "cycle.automation-cycle.station.api-platform-architecture.description": "Escolher a plataforma de automacao, o runtime, a abordagem de integracao, os controlos de governacao e as restricoes operacionais.", "cycle.automation-cycle.station.api-design.description": "Conceber o fluxo de trabalho de automacao, os gatilhos, os pontos de decisao, as integracoes, o tratamento de dados, os contratos de interface relevantes e os caminhos de excecao.", "cycle.automation-cycle.station.api-delivery.description": "Construa, teste, disponibilize, documente e opere a automação com propriedade, controlos e caminhos de reversão claros.", "cycle.automation-cycle.station.api-audit.description": "Reveja a prontidão, a qualidade, o risco, a conformidade, a supervisão humana, as evidências e os critérios de disponibilização da automação.", "cycle.automation-cycle.station.api-publishing.description": "Capacite utilizadores e operadores com descoberta, integração, instruções operacionais, caminhos de suporte e comunicação de alterações.", "cycle.automation-cycle.station.monitoring-and-improving.description": "Monitorize o desempenho da automação, exceções, fiabilidade, resultados dos utilizadores, impacto operacional e oportunidades de melhoria.", "group.core-stations.title": "Estações centrais do ciclo de vida da API", "group.core-stations.description": "As estações centrais do API Metro, onde as equipas podem aprender a criar e gerir APIs de forma eficaz.", "station.api-product-strategy.title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "station.api-product-strategy.description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia.", "station.api-product-strategy.why_it_matters": "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais.", "station.api-product-strategy.apply_in_work": "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "station.api-product-strategy.outcomes": "Uma proposta de valor e um público-alvo da API simples", "station.api-product-strategy.outcomes.1": "Linguagem partilhada entre o produto, a conceção e a tecnologia", "station.api-product-strategy.outcomes.2": "Um argumento sólido ou um caso para financiamento/aprovação", "station.api-product-strategy.how_it_works": "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "station.api-product-strategy.how_it_works.1": "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "station.api-product-strategy.how_it_works.2": "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "station.api-product-strategy.how_it_works.3": "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "station.api-consumer-experience.title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "station.api-consumer-experience.description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento.", "station.api-consumer-experience.why_it_matters": "As APIs excelentes não funcionam apenas - elas são intuitivas. Quer o consumidor seja um programador interno, um parceiro externo ou um agente de IA, a sua experiência determina a adoção.\n\nSnum plano de experiência claro:\n- Grandes APIs ficam sem uso\n- As equipas perdem tempo a tentar adivinhar como utilizar a sua API\n- Os ciclos de feedback estão quebrados ou ausentes.\n\nEsta estação ajuda-o a ver a sua API através dos olhos dos seus consumidores.", "station.api-consumer-experience.how_it_works": "Analise o Canvas da Proposta de Valor da API existente sob a perspectiva do consumidor da API. Mantenha as tarefas de negócios suportadas estáveis ​​e enriqueça os recursos que aliviam problemas e possibilitam ganhos com as preocupações do consumidor da API, para que elas possam orientar as decisões de conceção futuras.", "station.api-consumer-experience.how_it_works.1": "Utilize o Canvas do Percurso do Cliente para a jornada do consumidor da API, desde a descoberta e avaliação até a integração, resolução de problemas e uso contínuo.", "station.api-consumer-experience.how_it_works.2": "Utilize a jornada resultante para melhorar a integração, a documentação, o suporte e os ciclos de feedback para o consumidor da API.", "station.api-consumer-experience.apply_in_work": "Fornecer diretrizes, ferramentas e mecanismos de feedback para compreender, analisar e melhorar a experiência interna e externa dos programadores e parceiros.", "station.api-consumer-experience.outcomes": "Identifique e dê prioridade aos seus consumidores de API", "station.api-consumer-experience.outcomes.1": "Definir o percurso da experiência API", "station.api-consumer-experience.outcomes.2": "Planeamento da integração, documentação e feedback", "station.api-consumer-experience.outcomes.3": "Melhorar a adoção através de empatia genuína + Experiência do Programador (DX)", "station.api-platform-architecture.title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "station.api-platform-architecture.description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma.", "station.api-platform-architecture.why_it_matters": "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência.", "station.api-platform-architecture.apply_in_work": "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "station.api-platform-architecture.outcomes": "Corte APIs redundantes e reduza os custos da plataforma de nuvem", "station.api-platform-architecture.outcomes.1": "Implementar uma governação consistente snum forte controlo do topo para a base", "station.api-platform-architecture.outcomes.2": "Conceção para reutilização interna e escalabilidade externa", "station.api-platform-architecture.how_it_works": "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "station.api-platform-architecture.how_it_works.1": "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "station.api-platform-architecture.how_it_works.2": "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "station.api-platform-architecture.how_it_works.3": "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "station.api-design.title": "Conceção da API - Conceber APIs que proporcionem valor", "station.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.", "station.api-design.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.", "station.api-design.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.", "station.api-design.outcomes": "Conceção de API bem documentada e coerente", "station.api-design.outcomes.1": "Contratos de interface da API reutilizáveis e validados", "station.api-design.outcomes.2": "Desenhos alinhados com modelos de domínio e padrões de interação", "station.api-design.outcomes.3": "Rastreabilidade da conceção ao valor de negócio", "station.api-design.how_it_works": "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs.", "station.api-design.how_it_works.1": "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.", "station.api-design.how_it_works.2": "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.", "station.api-design.how_it_works.3": "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.", "station.api-design.how_it_works.4": "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.", "station.api-design.how_it_works.5": "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.", "station.api-design.how_it_works.6": "Aplique abordagens do tipo ‘contrato primeiro’ ou ‘design primeiro’ para capturar e validar o contrato de interface da API antes da implementação.", "station.api-design.how_it_works.7": "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.", "station.api-delivery.title": "Entrega da API - Fornecer APIs seguras e fiáveis", "station.api-delivery.description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia.", "station.api-delivery.why_it_matters": "Mesmo os melhores conceções de API falham se a entrega for inconsistente. Esta estação assegura que as suas APIs são construídas com qualidade, testadas exaustivamente e implementadas de forma fiável - permitindo iterações mais rápidas e maior confiança.", "station.api-delivery.apply_in_work": "Fornecer estruturas de codificação, bibliotecas e normas para a implementação de API. Implementar pipelines de CI/CD, estruturas de garantia de qualidade e ferramentas de automatização da disponibilização.", "station.api-delivery.outcomes": "APIs implementadas utilizando estruturas e padrões testados", "station.api-delivery.outcomes.1": "Pipelines de CI/CD fiáveis e automatizados", "station.api-delivery.outcomes.2": "Testes funcionais e não funcionais integrados", "station.api-delivery.outcomes.3": "Condutas de entrega seguras e conformes", "station.api-delivery.how_it_works": "Utilize as Melhores Práticas de Desenvolvimento de API como orientação para implementar o contrato validado com frameworks e bibliotecas estabelecidos, garantindo que o resultado seja reutilizável e sustentável.", "station.api-delivery.how_it_works.1": "Construa a implementação da API a partir do contrato validado usando frameworks, bibliotecas e padrões da equipa estabelecidos.", "station.api-delivery.how_it_works.2": "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "station.api-delivery.how_it_works.3": "Utilize pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "station.api-delivery.how_it_works.4": "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "station.api-delivery.how_it_works.5": "Utilize a lista de verificação de auditoria da API para garantir que a API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "station.api-audit.title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "station.api-audit.description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição.", "station.api-audit.why_it_matters": "As APIs são produtos de longa duração e devem atender às expectativas de qualidade, consistência e conformidade. A auditoria conecta as decisões de conceção, a implementação e a prontidão operacional a padrões definidos, reduzindo o risco antes da exposição.", "station.api-audit.apply_in_work": "Estabeleça um processo de auditoria consistente que avalie a prontidão da API em todas as etapas do ciclo de vida usando critérios, evidências e padrões definidos. Garanta que as lacunas sejam identificadas antecipadamente e resolvidas antes da publicação.", "station.api-audit.outcomes": "As APIs cumprems normas internas e externas", "station.api-audit.outcomes.1": "Documentação clara das decisões de conceção e implementação da API", "station.api-audit.outcomes.2": "Segurança, desempenho e conformidade validados", "station.api-audit.outcomes.3": "Redução do risco de problemas na produção", "station.api-audit.how_it_works": "Realizar auditorias para garantir que as APIs cumprems normas organizacionais, técnicas e legais antes da publicação.", "station.api-audit.how_it_works.1": "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas.", "station.api-audit.how_it_works.2": "Colaborar com as equipas de governação e especialistas no domínio para garantir que as APIs estão prontas para produção.", "station.api-publishing.title": "Publicação de API - Publique APIs com confiança", "station.api-publishing.description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos.", "station.api-publishing.why_it_matters": "A publicação é mais do que a disponibilização - trata-se de capacidade de descoberta, acesso e suporte. Se as APIs não forem publicadas corretamente, não serão utilizadas, reutilizadas ou protegidas de forma eficaz.", "station.api-publishing.apply_in_work": "Permitir que as APIs sejam publicadas no ambiente relevante e ter mecanismos claros de registo e acesso (por exemplo, chaves de API, OAuth, planos de subscrição), dependendo dos segmentos de consumidores de API e dos requisitos de segurança e conformidade.", "station.api-publishing.outcomes": "APIs publicadas no ambiente correto (privado, parceiro, público)", "station.api-publishing.outcomes.1": "Processos claros de integração e registo da API", "station.api-publishing.outcomes.2": "Documentação, modelos e políticas de segurança disponíveis", "station.api-publishing.outcomes.3": "APIs prontas para escala e governação", "station.api-publishing.how_it_works": "Publicar APIs nos gateways e ambientes adequados para apoiar a reutilização por vários consumidores de API.", "station.api-publishing.how_it_works.1": "Documentar a forma como os consumidores encontram e utilizam a API, incluindo processos de integração e registo.", "station.api-publishing.how_it_works.2": "Garantir que os modelos de segurança, a configuração da porta de ligação e os termos legais sejam claros e acessíveis aos consumidores.", "station.monitoring-and-improving.title": "Monitorização e melhoria - para valor API", "station.monitoring-and-improving.description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua.", "station.monitoring-and-improving.why_it_matters": "A entrega da API não pára no lançamento. Sem monitorização, as equipas não podem melhorar a adoção, o desempenho ou o ROI. Esta estação garante que as APIs permaneçam úteis, seguras e evoluindo com as necessidades do negócio.", "station.monitoring-and-improving.apply_in_work": "Criar quadros analíticos para acompanhar o desempenho e o envolvimento. Desenvolver ciclos de feedback, ferramentas de análise e estratégias de envolvimento para APIs.", "station.monitoring-and-improving.outcomes": "Métricas de desempenho e utilização definidas e controladas", "station.monitoring-and-improving.outcomes.1": "Ciclos de feedback do programador em vigor", "station.monitoring-and-improving.outcomes.2": "Questões identificadas e tratadas continuamente", "station.monitoring-and-improving.outcomes.3": "Iteração da API alinhada com as necessidades dos utilizadores", "station.monitoring-and-improving.how_it_works": "Monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "station.monitoring-and-improving.how_it_works.1": "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API.", "station.monitoring-and-improving.how_it_works.2": "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua.", "group.sub-stations.title": "Sub-estações do ciclo de vida API", "group.sub-stations.description": "Subestações que fornecem recursos adicionais, ferramentas e boas práticas para equipas de API.", "station.user-experience.title": "Experiência do utilizador - Conceber APIs com o utilizador em mente", "station.user-experience.description": "Assegurar que as APIs são concebidas tendo em mente o utilizador final, proporcionando uma experiência intuitiva e sem descontinuidades.", "station.user-experience.why_it_matters": "As APIs não são apenas produtos técnicos; são produtos virados para o utilizador. Uma má experiência do utilizador pode levar a uma baixa adoção e à frustração. Esta estação ajuda as equipas a conceber APIs que sejam fáceis de utilizar e que satisfaçam as necessidades dos consumidores.", "station.user-experience.apply_in_work": "Fornecer orientações, modelos e ferramentas de experiência do utilizador para a conceção de API. Assegurar que as equipas seguem práticas de design centradas no utilizador e incorporam o feedback do utilizador nas iterações da API.", "station.user-experience.outcomes": "APIs concebidas a pensar nas necessidades dos utilizadores", "station.user-experience.outcomes.1": "Interfaces de utilizador intuitivas e coerentes", "station.user-experience.outcomes.2": "Feedback do utilizador incorporado na conceção da API", "station.user-experience.outcomes.3": "Maior satisfação e adoção por parte dos utilizadores", "station.user-experience.how_it_works": "Utilizar as personas dos utilizadores para compreender as necessidades e expectativas dos utilizadores finais", "station.user-experience.how_it_works.1": "Realize estudos de utilizadores para obter informações sobre a forma como os consumidores interagem com os serviços do ecossistema ou com as suas aplicações que consomem API.", "station.user-experience.how_it_works.2": "Documentar os requisitos da experiência do utilizador para que possam ser utilizados na conceção da API, garantindo que são intuitivos e fáceis de utilizar.", "station.market-insights.title": "Informações sobre o mercado - Compreender o cenário das API", "station.market-insights.description": "Analisar as tendências do mercado, as APIs da concorrência e as normas da indústria para informar a estratégia de API.", "station.market-insights.why_it_matters": "Compreender o panorama do mercado ajuda as equipas a identificar oportunidades, evitar armadilhas e alinhar as suas APIs com as normas da indústria. Esta estação fornece ferramentas para analisar as tendências do mercado e as ofertas dos concorrentes.", "station.market-insights.apply_in_work": "Fornecer ferramentas de pesquisa de mercado, modelos de análise da concorrência e recursos de normas do sector. Assegurar que as equipas se mantêm informadas sobre as tendências do mercado e incorporam os conhecimentos na estratégia de API.", "station.market-insights.outcomes": "Análise das tendências do mercado e das APIs dos concorrentes", "station.market-insights.outcomes.1": "Identificação das normas e boas práticas do sector", "station.market-insights.outcomes.2": "Estratégia de API alinhada com as necessidades do mercado", "station.market-insights.outcomes.3": "Tomada de decisões informadas com base em conhecimentos do mercado", "station.market-insights.how_it_works": "Realizar estudos de mercado para identificar tendências, oportunidades e ameaças no panorama das APIs.", "station.market-insights.how_it_works.1": "Analisar as APIs da concorrência para compreender os seus pontos fortes, fracos e pontos de venda únicos.", "station.market-insights.how_it_works.2": "Identificar as normas e as boas práticas do sector para garantir que as APIs são competitivas e estão em conformidade.", "station.business-goals.title": "Objectivos comerciais - Alinhar as APIs com os objetivos de negócio", "station.business-goals.description": "Assegurar que as APIs estão alinhadas com os objetivos de negócio e contribuem para os objetivos organizacionais globais.", "station.business-goals.why_it_matters": "As APIs não devem ser construídas isoladamente; elas devem apoiar e impulsionar os objetivos de negócio. Esta estação ajuda as equipas a alinharem as suas APIs com os objetivos estratégicos, assegurando que fornecnum verdadeiro valor de negócio.", "station.business-goals.apply_in_work": "Fornecer estruturas, modelos e ferramentas de alinhamento comercial para definir o valor de negócio da API. Garantir que as equipas revejam e alinhem regularmente as APIs com os objetivos de negócio em mudança.", "station.business-goals.outcomes": "APIs alinhadas com os objetivos de negócio", "station.business-goals.outcomes.1": "Valor de negócio claro definido para cada API", "station.business-goals.outcomes.2": "Adesão e apoio das partes interessadas às iniciativas API", "station.business-goals.outcomes.3": "As APIs contribuem para o sucesso organizacional", "station.business-goals.how_it_works": "Definir os objetivos de negócio e a forma como as APIs podem apoiá-los utilizando **o Business Model Canvas**. Se o seu negócio é fornecer APIs, passe pela *estação de Estratégia de Produto de API* e preencha **o Modelo de Negócio de API Canvas**.", "station.business-goals.how_it_works.1": "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "station.business-goals.how_it_works.2": "Envolver as partes interessadas para garantir o alinhamento e o apoio às iniciativas da API.", "station.competitive-analysis.title": "Análise competitiva - Fique à frente no mercado de API", "station.competitive-analysis.description": "Analisar as APIs dos concorrentes para identificar pontos fortes, pontos fracos e oportunidades de diferenciação.", "station.competitive-analysis.why_it_matters": "Compreender o cenário competitivo ajuda as equipas a identificar lacunas, oportunidades e áreas de melhoria nas suas APIs. Esta estação fornece ferramentas para analisar os concorrentes e informar a estratégia de API.", "station.competitive-analysis.apply_in_work": "Fornecer ferramentas, modelos e recursos de análise da concorrência. Assegurar que as equipas analisam regularmente os concorrentes e incorporam os conhecimentos na estratégia e conceção da API.", "station.competitive-analysis.outcomes": "APIs da concorrência analisadas quanto aos pontos fortes e fracos", "station.competitive-analysis.outcomes.1": "Identificação de oportunidades de diferenciação", "station.competitive-analysis.outcomes.2": "Estratégia de API baseada em informações sobre a concorrência", "station.competitive-analysis.outcomes.3": "Aumento da competitividade no mercado de API", "station.competitive-analysis.how_it_works": "Efetuar uma análise da concorrência para identificar os principais concorrentes, as suas ofertas de API e os seus pontos fortes e fracos.", "station.competitive-analysis.how_it_works.1": "Identifique as lacunas no mercado que as suas APIs podem preencher, com base nas ofertas da concorrência.", "station.competitive-analysis.how_it_works.2": "Desenvolva uma estratégia de diferenciação que destaque as características e benefícios únicos das suas APIs.", "station.ecosystem-vision.title": "Visão do ecossistema - Criar APIs para um ecossistema próspero", "station.ecosystem-vision.description": "Crie uma visão de como as suas APIs se encaixam num ecossistema maior, permitindo a colaboração e a inovação.", "station.ecosystem-vision.why_it_matters": "As APIs não são produtos autónomos; fazem parte de um ecossistema maior. Esta estação ajuda as equipas a definir como as suas APIs interagem com outros sistemas, plataformas e serviços para criar um ecossistema próspero que promove a colaboração e a inovação.", "station.ecosystem-vision.apply_in_work": "Fornecer estruturas de visão do ecossistema, estratégias de envolvimento de parceiros e diretrizes de integração. Garantir que as equipas concebem APIs com o ecossistema em mente e promovem a colaboração entre parceiros.", "station.ecosystem-vision.outcomes": "Definição de uma visão clara do ecossistema para as API", "station.ecosystem-vision.outcomes.1": "APIs concebidas para permitir a colaboração e a integração", "station.ecosystem-vision.outcomes.2": "Parceiros do ecossistema identificados e envolvidos", "station.ecosystem-vision.outcomes.3": "As APIs contribuem para um ecossistema dinâmico", "station.ecosystem-vision.how_it_works": "Defina a visão do ecossistema para as suas APIs, incluindo a forma como estas irão interagir com outros sistemas e plataformas.", "station.ecosystem-vision.how_it_works.1": "Identificar os principais parceiros e intervenientes do ecosistema que irão beneficiar ou contribuir para o ecosistema.", "station.ecosystem-vision.how_it_works.2": "Conceber APIs para permitir uma integração e colaboração perfeitas no ecossistema.", "station.scalable-infrastructure.title": "Infraestrutura escalável - Construir APIs sobre uma base sólida", "station.scalable-infrastructure.description": "Certifique-se de que a sua infraestrutura de API pode ser dimensionada para responder à crescente procura e suportar uma elevada disponibilidade.", "station.scalable-infrastructure.why_it_matters": "As APIs devem ser construídas numa infraestrutura robusta que possa lidar com o aumento do tráfego e garantir uma elevada disponibilidade. Esta estação fornece diretrizes para a conceção e implementação de uma infraestrutura escalável que suporte o crescimento e o desempenho da API.", "station.scalable-infrastructure.apply_in_work": "Fornecer diretrizes de conceção de infra-estruturas, padrões nativos da nuvem e ferramentas de monitorização. Assegurar que as equipas implementam uma infraestrutura escalável que se pode adaptar às exigências em mudança e suportar o desempenho da API.", "station.scalable-infrastructure.outcomes": "Infraestrutura API escalável e resiliente", "station.scalable-infrastructure.outcomes.1": "Elevada disponibilidade e desempenho sob carga", "station.scalable-infrastructure.outcomes.2": "Infra-estruturas concebidas para o crescimento futuro", "station.scalable-infrastructure.outcomes.3": "Redução do tempo de inatividade e melhoria da experiência do utilizador", "station.scalable-infrastructure.how_it_works": "Conceber a infraestrutura da API para ser escalável e resiliente, utilizando padrões e tecnologias nativos da nuvem.", "station.scalable-infrastructure.how_it_works.1": "Implementar o equilíbrio de carga, o armazenamento em cache e outras técnicas para garantir uma elevada disponibilidade e desempenho. Recolher os requisitos de infraestrutura das equipas de API utilizando o Canvas de Capacidade", "station.scalable-infrastructure.how_it_works.2": "Monitorizar o desempenho e a capacidade da infraestrutura para garantir que esta consegue dar resposta à crescente procura.", "station.legal-and-compliance.title": "Legal e Conformidade - Garantir que as APIs cumprems normas regulamentares", "station.legal-and-compliance.description": "Garanta que as APIs cumprem os requisitos legais e regulamentares, protegendo a sua organização e os seus utilizadores.", "station.legal-and-compliance.why_it_matters": "As APIs devem cumprir as normas legais e regulamentares para proteger a sua organização e os utilizadores. Esta estação fornece ferramentas e diretrizes para garantir que as APIs cumprem os requisitos de conformidade, reduzindo os riscos legais e garantindo a proteção de dados.", "station.legal-and-compliance.apply_in_work": "Fornecer estruturas legais e de conformidade, listas de verificação e ferramentas para garantir a conformidade da API. Assegurar que as equipas compreendem e implementam os requisitos legais na conceção, desenvolvimento e publicação de API.", "station.legal-and-compliance.outcomes": "APIs em conformidade com as normas legais e regulamentares", "station.legal-and-compliance.outcomes.1": "Cumprimento dos requisitos de proteção de dados e privacidade", "station.legal-and-compliance.outcomes.2": "Riscos jurídicos identificados e atenuados", "station.legal-and-compliance.outcomes.3": "Documentação clara das medidas de conformidade", "station.legal-and-compliance.how_it_works": "Identifique os requisitos legais e regulamentares que se aplicam às suas APIs, tais como proteção de dados, privacidade e normas de segurança.", "station.legal-and-compliance.how_it_works.1": "Implementar medidas para garantir que as APIs cumprem estes requisitos, incluindo encriptação de dados, controlos de acesso e pistas de auditoria.", "station.legal-and-compliance.how_it_works.2": "Documentar as medidas de conformidade e garantir que são comunicadas às partes interessadas e aos consumidores.", "station.security-and-privacy.title": "Segurança e privacidade - Proteja as suas APIs e os seus utilizadores", "station.security-and-privacy.description": "Implementar medidas de segurança e privacidade para proteger as APIs e os dados dos utilizadores contra ameaças e violações.", "station.security-and-privacy.why_it_matters": "As APIs são vulneráveis a ameaças de segurança e violações de dados. Esta estação fornece orientações para a implementação de medidas de segurança e privacidade que protegem as APIs e os dados dos utilizadores, garantindo a confiança e a conformidade.", "station.security-and-privacy.apply_in_work": "Fornecer estruturas de segurança, ferramentas e boas práticas para a segurança e privacidade da API. Assegurar que as equipas implementam medidas de segurança em todo o ciclo de vida da API, desde a conceção até à publicação e monitorização.", "station.security-and-privacy.outcomes": "APIs protegidas contra ameaças e vulnerabilidades", "station.security-and-privacy.outcomes.1": "Dados do utilizador protegidos através de medidas de privacidade", "station.security-and-privacy.outcomes.2": "Boas práticas de segurança implementadas na conceção e desenvolvimento de API", "station.security-and-privacy.outcomes.3": "Conformidade com as normas e regulamentos de segurança", "station.security-and-privacy.how_it_works": "Implemente medidas de segurança como autenticação, autorização, encriptação e limitação de taxas para proteger as APIs de ameaças.", "station.security-and-privacy.how_it_works.1": "Garantir a privacidade dos dados dos utilizadores através da implementação de medidas de proteção de dados, como a anonimização e os controlos de acesso.", "station.security-and-privacy.how_it_works.2": "Efetuar auditorias de segurança regulares e avaliações de vulnerabilidade para identificar e atenuar os riscos.", "station.design-standards.title": "Normas de conceção - Garantir uma conceção de API consistente e de alta qualidade", "station.design-standards.description": "Estabelecer normas e diretrizes de design para garantir um design API consistente e de alta qualidade em toda a organização.", "station.design-standards.why_it_matters": "Um conceção de API consistente e de alta qualidade é essencial para a usabilidade, manutenção e escalabilidade. Esta estação fornece normas e diretrizes de design que ajudam as equipas a criar APIs que são fáceis de utilizar, compreender e manter.", "station.design-standards.apply_in_work": "Fornecer documentação sobre normas de conceção, componentes reutilizáveis e processos de revisão da conceção. Assegurar que as equipas seguem as normas de conceção e realizam revisões regulares para manter uma conceção de API de alta qualidade.", "station.design-standards.outcomes": "Conceção consistente da API em toda a organização", "station.design-standards.outcomes.1": "APIs de alta qualidade que satisfazem as necessidades dos utilizadores", "station.design-standards.outcomes.2": "Componentes e padrões de conceção reutilizáveis", "station.design-standards.outcomes.3": "Redução das inconsistências de conceção e da dívida técnica", "station.design-standards.how_it_works": "Definir normas e diretrizes de conceção para a conceção de API, incluindo convenções de nomenclatura, formatos de resposta e tratamento de erros.", "station.design-standards.how_it_works.1": "Criar padrões de conceção e componentes reutilizáveis que as equipas possam utilizar para garantir a consistência e a qualidade.", "station.design-standards.how_it_works.2": "Efetuar revisões e auditorias de conceção para garantir o cumprimento das normas de conceção e identificar áreas a melhorar.", "station.vendor-management.title": "Gestão de fornecedores - Gerir integrações de APIs de terceiros", "station.vendor-management.description": "Gerir eficazmente os fornecedores e as integrações de API de terceiros para garantir a fiabilidade e a conformidade.", "station.vendor-management.why_it_matters": "As APIs de terceiros podem introduzir riscos e dependências que afectam o seu ecossistema de API. Esta estação fornece diretrizes para gerir as relações com os fornecedores, garantindo a fiabilidade, a conformidade e o alinhamento com a sua estratégia de API.", "station.vendor-management.apply_in_work": "Fornecer estruturas de gestão de fornecedores, critérios de avaliação e ferramentas de monitorização. Assegurar que as equipas gerem eficazmente os fornecedores de API de terceiros, garantindo a fiabilidade, a conformidade e o alinhamento com as normas organizacionais.", "station.vendor-management.outcomes": "Estabelecimento de processos eficazes de gestão de fornecedores", "station.vendor-management.outcomes.1": "APIs de terceiros integradas de forma fiável e segura", "station.vendor-management.outcomes.2": "Conformidade do fornecedor com as normas organizacionais", "station.vendor-management.outcomes.3": "Redução dos riscos associados a dependências de terceiros", "station.vendor-management.how_it_works": "Estabelecer processos de gestão de fornecedores para avaliar, integrar e monitorizar fornecedores de API de terceiros.", "station.vendor-management.how_it_works.1": "Definir critérios para avaliar as APIs dos fornecedores, incluindo fiabilidade, segurança e conformidade.", "station.vendor-management.how_it_works.2": "Monitorizar o desempenho dos fornecedores e o cumprimento dos acordos de nível de serviço (SLA) e das normas organizacionais.", "station.contract-design.title": "Conceção de contratos - Definir contratos de interface da API claros", "station.contract-design.description": "Criar contratos de interface da API claros e bem definidos que descrevam as expectativas, responsabilidades e diretrizes de utilização.", "station.contract-design.why_it_matters": "Os contratos de interface da API são essenciais para garantir a clareza e o alinhamento entre os fornecedores e os consumidores de API. Esta estação fornece diretrizes para a conceção de contratos de interface da API que sejam claros, abrangentes e fáceis de compreender.", "station.contract-design.apply_in_work": "Fornecer modelos de design de contratos, formatos normalizados e processos de revisão. Assegurar que as equipas criam contratos de interface da API claros e bem definidos que descrevem as expectativas, responsabilidades e diretrizes de utilização.", "station.contract-design.outcomes": "Contratos de interface da API claros definidos para cada API", "station.contract-design.outcomes.1": "Expectativas e responsabilidades definidas para os fornecedores e consumidores de API", "station.contract-design.outcomes.2": "Orientações de utilização e boas práticas documentadas", "station.contract-design.outcomes.3": "Redução de mal-entendidos e litígios sobre a utilização da API", "station.contract-design.how_it_works": "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "station.contract-design.how_it_works.1": "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar.", "station.contract-design.how_it_works.2": "Assegurar que os contratos de interface da API são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza.", "station.development.title": "Desenvolvimento - Criar APIs com as boas práticas", "station.development.description": "Implementar APIs utilizando as boas práticas e estruturas para garantir a qualidade, a capacidade de manutenção e a escalabilidade.", "station.development.why_it_matters": "O desenvolvimento de API é uma fase crítica que determina a qualidade e a fiabilidade da API. Esta estação fornece as boas práticas e estruturas para o desenvolvimento de APIs, garantindo que as APIs são construídas de acordo com padrões elevados e podem ser mantidas e escaladas de forma eficaz.", "station.development.apply_in_work": "Fornecer estruturas de desenvolvimento, bibliotecas e normas de codificação para a implementação da API. Garantir que as equipas seguem as boas práticas e realizam revisões de código para manter um desenvolvimento de API de alta qualidade.", "station.development.outcomes": "APIs desenvolvidas utilizando as boas práticas e estruturas", "station.development.outcomes.1": "APIs de alta qualidade, fáceis de manter e escaláveis", "station.development.outcomes.2": "Seguimento de normas e práticas de codificação consistentes", "station.development.outcomes.3": "Redução do tempo de desenvolvimento e da dívida técnica", "station.development.how_it_works": "Utilizar estruturas e bibliotecas estabelecidas para implementar APIs, assegurando a sua reutilização e manutenção.", "station.development.how_it_works.1": "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "station.development.how_it_works.2": "Seguir as normas de codificação e as boas práticas para garantir um desenvolvimento de API consistente e de alta qualidade.", "station.ci-cd.title": "CI/CD - Automatizar a entrega da API", "station.ci-cd.description": "Implementar pipelines de integração contínua e entrega contínua (CI/CD) para automatizar a entrega de API e garantir uma qualidade consistente.", "station.ci-cd.why_it_matters": "A CI/CD é essencial para garantir que as APIs sejam entregues rapidamente, de forma confiável e com alta qualidade. Esta estação fornece diretrizes para a implementação de pipelines de CI/CD que automatizam os processos de criação, teste e disponibilização de APIs.", "station.ci-cd.apply_in_work": "Fornecer estruturas, ferramentas e boas práticas de CI/CD para a entrega de API. Garantir que as equipas implementam pipelines automatizados que suportam a integração, os testes e a implementação contínuos de APIs.", "station.ci-cd.outcomes": "Pipelines CI/CD automatizados estabelecidos para a entrega de API", "station.ci-cd.outcomes.1": "Qualidade e rastreabilidade consistentes na entrega de API", "station.ci-cd.outcomes.2": "iterações mais rápidas e redução do tempo de colocação no mercado", "station.ci-cd.outcomes.3": "Melhoria da colaboração e dos ciclos de feedback no desenvolvimento de API", "station.ci-cd.how_it_works": "Utilize pipelines CI/CD para automatizar os processos de construção, teste e disponibilização, garantindo qualidade e rastreabilidade consistentes.", "station.ci-cd.how_it_works.1": "Integrar testes funcionais e não funcionais no pipeline CI/CD para garantir que as APIs cumprems normas de qualidade.", "station.ci-cd.how_it_works.2": "Implementar verificações de segurança automatizadas e validações de conformidade no pipeline CI/CD para garantir que as APIs são seguras e compatíveis.", "station.test-automation.title": "Automatização de testes - Garantir a qualidade da API", "station.test-automation.description": "Implementar práticas de teste automatizadas para garantir a qualidade, fiabilidade e desempenho da API.", "station.test-automation.why_it_matters": "Os testes automatizados são cruciais para garantir que as APIs funcionam corretamente e cumprems normas de qualidade. Esta estação fornece diretrizes para a implementação de práticas de teste automatizado que abrangem testes funcionais, de segurança e de desempenho para APIs.", "station.test-automation.apply_in_work": "Fornecer estruturas de automatização de testes, ferramentas e boas práticas para testes de API. Assegurar que as equipas implementam testes automatizados que abrangem aspectos funcionais, de segurança e de desempenho das APIs.", "station.test-automation.outcomes": "Práticas de teste automatizadas implementadas para APIs", "station.test-automation.outcomes.1": "Testes funcionais, de segurança e de desempenho automatizados", "station.test-automation.outcomes.2": "Redução do esforço de teste manual e aumento da cobertura dos testes", "station.test-automation.outcomes.3": "Melhoria da fiabilidade e da qualidade da API", "station.test-automation.how_it_works": "Utilizar ferramentas de teste automatizadas para validar a funcionalidade, a segurança e o desempenho da API.", "station.test-automation.how_it_works.1": "Implementar estruturas de automatização de testes que apoiem os testes de contrato, os testes de integração e os testes de ponta a ponta.", "station.test-automation.how_it_works.2": "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "station.release-management.title": "Gestão de versões - Gerir eficazmente as versões da API", "station.release-management.description": "Implementar práticas de gestão de lançamentos para garantir lançamentos de API sem problemas e controlados.", "station.release-management.why_it_matters": "A gestão eficaz de lançamentos é essencial para garantir que os lançamentos de APIs sejam fáceis, controlados e alinhados com as necessidades do negócio. Esta estação fornece diretrizes para a gestão de lançamentos de API, incluindo versões, estratégias de implementação e procedimentos de reversão.", "station.release-management.apply_in_work": "Fornecer estruturas de gestão de versões, diretrizes de controlo de versões e estratégias de implementação. Assegurar que as equipas seguem as boas práticas para a gestão de lançamentos de API, incluindo procedimentos de versão, implementação e reversão.", "station.release-management.outcomes": "Lançamentos de API controlados e sem problemas", "station.release-management.outcomes.1": "Definição de estratégias de versão e disponibilização", "station.release-management.outcomes.2": "Procedimentos de reversão estabelecidos para libertações de API", "station.release-management.outcomes.3": "Redução dos riscos associados às alterações da API", "station.release-management.how_it_works": "Definir estratégias de controlo de versões para as APIs para gerir as alterações e garantir a compatibilidade com as versões anteriores.", "station.release-management.how_it_works.1": "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "station.release-management.how_it_works.2": "Estabelecer procedimentos de reversão para reverter rapidamente as alterações em caso de problemas durante os lançamentos da API.", "station.service-agreements.title": "Acordos de serviço - Definir níveis de serviço de API", "station.service-agreements.description": "Estabelecer acordos de serviço que definam as expectativas, os níveis de serviço e as responsabilidades dos fornecedores e consumidores de API.", "station.service-agreements.why_it_matters": "Os acordos de serviço são essenciais para garantir a clareza e o alinhamento entre os fornecedores de API e os consumidores. Esta estação fornece diretrizes para a criação de acordos de serviço que definem expectativas, níveis de serviço e responsabilidades, reduzindo mal-entendidos e disputas.", "station.service-agreements.apply_in_work": "Fornecer modelos de contratos de serviço, formatos normalizados e processos de revisão. Garantir que as equipas criam contratos de serviço claros e bem definidos que descrevem as expectativas, os níveis de serviço e as responsabilidades dos fornecedores e consumidores de API.", "station.service-agreements.outcomes": "Acordos de serviço claros definidos para cada API", "station.service-agreements.outcomes.1": "Expectativas e níveis de serviço definidos para fornecedores e consumidores de API", "station.service-agreements.outcomes.2": "Responsabilidades e processos de apoio documentados", "station.service-agreements.outcomes.3": "Melhoria da comunicação e da colaboração entre as equipas de API", "station.service-agreements.how_it_works": "Defina acordos de serviço que descrevam as expectativas, os níveis de serviço e as responsabilidades de cada API.", "station.service-agreements.how_it_works.1": "Utilize formatos normalizados para criar contratos de serviço legíveis por máquina que sejam fáceis de partilhar e validar.", "station.service-agreements.how_it_works.2": "Assegurar que os acordos de serviço são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza.", "station.api-consumer-adoption.title": "Adoção pelo consumidor da API - Impulsionar a utilização da API", "station.api-consumer-adoption.description": "Implementar estratégias para promover a adoção e o envolvimento dos consumidores de API, assegurando que as APIs são utilizadas eficazmente.", "station.api-consumer-adoption.why_it_matters": "A adoção pelos consumidores de APIs é crucial para a concretização do valor das APIs. Esta estação fornece estratégias e boas práticas para envolver os consumidores de API, garantindo que eles entendam como utilizar as APIs de forma eficaz e obter valor delas.", "station.api-consumer-adoption.apply_in_work": "Fornecer recursos de integração, materiais educativos e estratégias de envolvimento para os consumidores da API. Assegurar que as equipas implementam estratégias que promovem a adoção, o envolvimento e a satisfação dos consumidores da API.", "station.api-consumer-adoption.outcomes": "Estratégias de adoção pelos consumidores da API implementadas", "station.api-consumer-adoption.outcomes.1": "Aumento da utilização e do envolvimento da API", "station.api-consumer-adoption.outcomes.2": "Consumidores da API informados sobre as características e vantagens da API", "station.api-consumer-adoption.outcomes.3": "Melhoria da satisfação e da lealdade do consumidor API", "station.api-consumer-adoption.how_it_works": "Desenvolver processos de integração e recursos para ajudar os consumidores de API a compreender como utilizar as APIs de forma eficaz.", "station.api-consumer-adoption.how_it_works.1": "Criar materiais educativos (por exemplo, tutoriais, documentação) que expliquem as características, as vantagens e os padrões de utilização da API.", "station.api-consumer-adoption.how_it_works.2": "Interagir com os consumidores da API através de ciclos de feedback, canais de apoio e fóruns da comunidade para compreender as suas necessidades e melhorar a adoção da API.", "station.api-promotion.title": "Promoção da API - Aumente a visibilidade e a utilização da API", "station.api-promotion.description": "Promover as APIs para aumentar a visibilidade, a utilização e a adoção entre os públicos-alvo.", "station.api-promotion.why_it_matters": "A promoção das APIs é essencial para aumentar a sua visibilidade e impulsionar a sua utilização. Esta estação fornece estratégias e boas práticas para promover eficazmente as APIs junto de públicos-alvo, assegurando que estes têm conhecimento das APIs e compreendem o seu valor.", "station.api-promotion.apply_in_work": "Fornecer estratégias de marketing, materiais promocionais e recursos de envolvimento da comunidade. Assegurar que as equipas implementam estratégias eficazes de promoção da API que aumentam a visibilidade, a utilização e a adoção entre os públicos-alvo.", "station.api-promotion.outcomes": "Estratégias de promoção da API implementadas", "station.api-promotion.outcomes.1": "Maior visibilidade e conhecimento da API", "station.api-promotion.outcomes.2": "Taxas de utilização e adoção de API mais elevadas", "station.api-promotion.outcomes.3": "Melhoria do envolvimento e da satisfação dos consumidores da API", "station.api-promotion.how_it_works": "Desenvolver estratégias de marketing para promover as APIs junto de públicos-alvo, incluindo redes sociais, blogues e webinars.", "station.api-promotion.how_it_works.1": "Criar materiais promocionais (por exemplo, estudos de casos, histórias de sucesso) que realcem o valor e as vantagens das APIs.", "station.api-promotion.how_it_works.2": "Participar em comunidades e fóruns de API para partilhar actualizações da API, recolher feedback e promover a utilização da API.", "station.partner-integration.title": "Integração de parceiros - Colaborar com parceiros", "station.partner-integration.description": "Facilitar as integrações de parceiros para melhorar as capacidades da API e expandir o alcance.", "station.partner-integration.why_it_matters": "As integrações de parceiros podem melhorar as capacidades da API e expandir o seu alcance. Esta estação fornece diretrizes para colaborar com os parceiros na integração das suas APIs, garantindo uma interoperabilidade perfeita e a criação de valor.", "station.partner-integration.apply_in_work": "Fornecer estruturas de integração de parceiros, diretrizes e ferramentas de monitorização. Garantir que as equipas colaboram eficazmente com os parceiros para melhorar as capacidades da API, expandir o alcance e impulsionar a inovação.", "station.partner-integration.outcomes": "Processos de integração de parceiros estabelecidos", "station.partner-integration.outcomes.1": "Capacidades API melhoradas através de API de parceiros", "station.partner-integration.outcomes.2": "Maior alcance e oportunidades de mercado através de parcerias", "station.partner-integration.outcomes.3": "Melhoria da colaboração e da inovação com os parceiros", "station.partner-integration.how_it_works": "Identifique potenciais parceiros cujas APIs possam melhorar as suas capacidades de API e a sua proposta de valor.", "station.partner-integration.how_it_works.1": "Estabelecer processos de integração e orientações para colaborar com os parceiros, incluindo a integração técnica, a partilha de dados e o apoio.", "station.partner-integration.how_it_works.2": "Monitorize o desempenho e a conformidade da API do parceiro para garantir a fiabilidade e o alinhamento com a sua estratégia de API.", "station.api-mindset.title": "Mentalidade API - Promover uma cultura API-First", "station.api-mindset.description": "Cultivar uma mentalidade API-first em toda a organização para impulsionar a inovação e a colaboração.", "station.api-mindset.why_it_matters": "Uma mentalidade API-first é essencial para promover a inovação e a colaboração em toda a organização. Esta estação fornece estratégias para cultivar uma cultura API-first, garantindo que as APIs sejam vistas como activos estratégicos que geram valor de negócio.", "station.api-mindset.apply_in_work": "Fornecer programas de formação, recursos e estratégias de comunicação para promover uma cultura de prioridade à API. Assegurar que as equipas compreendem o valor das APIs e estão habilitadas a conduzir a estratégia e as iniciativas das APIs.", "station.api-mindset.outcomes": "Cultura API-first estabelecida em toda a organização", "station.api-mindset.outcomes.1": "Maior inovação e colaboração através de API", "station.api-mindset.outcomes.2": "Equipas de API habilitadas a conduzir a estratégia e as iniciativas de API", "station.api-mindset.outcomes.3": "Melhoria do alinhamento entre os objetivos de negócio e o desenvolvimento de API", "station.api-mindset.how_it_works": "Promover o valor das APIs como activos estratégicos que geram valor de negócio e inovação.", "station.api-mindset.how_it_works.1": "Incentivar a colaboração multifuncional entre equipas de API, unidades empresariais e partes interessadas para alinhar as iniciativas de API com os objetivos empresariais.", "station.api-mindset.how_it_works.2": "Fornecer formação e recursos para ajudar as equipas a adotar uma mentalidade de prioridade à API e a compreender as vantagens das APIs.", "station.roles-and-responsibilities.title": "Funções e responsabilidades - Definir as estruturas da equipa API", "station.roles-and-responsibilities.description": "Definir funções e responsabilidades claras para as equipas de API para garantir uma colaboração e responsabilização eficazes.", "station.roles-and-responsibilities.why_it_matters": "Funções e responsabilidades claras são essenciais para uma colaboração e responsabilidade eficazes nas equipas de API. Esta estação fornece diretrizes para a definição das estruturas, funções e responsabilidades da equipa, assegurando que todos compreendem as suas contribuições para as iniciativas da API.", "station.roles-and-responsibilities.apply_in_work": "Fornecer orientações sobre a estrutura da equipa, definições de funções e estratégias de comunicação. Assegurar que as equipas têm funções e responsabilidades claras que promovem a colaboração eficaz e a responsabilização nas iniciativas da API.", "station.roles-and-responsibilities.outcomes": "Funções e responsabilidades claras definidas para as equipas de API", "station.roles-and-responsibilities.outcomes.1": "Colaboração e responsabilização eficazes nas equipas API", "station.roles-and-responsibilities.outcomes.2": "Melhoria da comunicação e do alinhamento entre os membros da equipa", "station.roles-and-responsibilities.outcomes.3": "Redução da confusão e da sobreposição de responsabilidades", "station.roles-and-responsibilities.how_it_works": "Definir estruturas de equipa e funções para equipas de API, incluindo proprietários de produtos de API, programadores, arquitectos e operações.", "station.roles-and-responsibilities.how_it_works.1": "Estabelecer responsabilidades claras para cada função, incluindo a conceção, o desenvolvimento, os testes e as operações da API.", "station.roles-and-responsibilities.how_it_works.2": "Assegurar que as funções e responsabilidades são comunicadas a todos os membros da equipa e partes interessadas para garantir o alinhamento.", "station.upskilling.title": "Upskilling - Melhorar as competências e conhecimentos em matéria de API", "station.upskilling.description": "Fornecer formação e recursos para melhorar as competências e os conhecimentos sobre API em toda a organização.", "station.upskilling.why_it_matters": "A aprendizagem contínua e a atualização de competências são essenciais para manter as equipas de API actualizadas com as mais recentes tecnologias, práticas e tendências. Esta estação fornece programas de formação e recursos para melhorar as competências e os conhecimentos sobre API, garantindo que as equipas estão equipadas para fornecer APIs de alta qualidade.", "station.upskilling.apply_in_work": "Fornecer programas de formação, recursos e ferramentas de avaliação para melhorar as competências e os conhecimentos em matéria de API. Assegurar que as equipas têm acesso a oportunidades de aprendizagem contínua que lhes permitam impulsionar a inovação e a qualidade da API.", "station.upskilling.outcomes": "Melhoria das competências e conhecimentos em matéria de API em toda a organização", "station.upskilling.outcomes.1": "Maior proficiência na conceção, desenvolvimento e gestão de API", "station.upskilling.outcomes.2": "Melhoria da capacidade de adoção de novas tecnologias e práticas", "station.upskilling.outcomes.3": "Equipas capacitadas para impulsionar a inovação e a qualidade da API", "station.upskilling.how_it_works": "Identificar as principais competências e áreas de conhecimento da API que precisam de ser melhoradas, como a conceção, a segurança e o desempenho da API.", "station.operating-guidelines.title": "Diretrizes operacionais - Estabelecer a governação da API", "station.operating-guidelines.description": "Estabelecer diretrizes operacionais e práticas de governação para garantir uma gestão e qualidade consistentes da API.", "station.operating-guidelines.why_it_matters": "A governação eficaz da API é essencial para garantir uma gestão, qualidade e conformidade consistentes da API. Esta estação fornece diretrizes operacionais e práticas de governação que ajudam as equipas a gerir as APIs de forma eficaz, assegurando o seu alinhamento com as normas organizacionais e as boas práticas.", "station.operating-guidelines.apply_in_work": "Fornecer diretrizes operacionais, quadros de governação e ferramentas de monitorização para a gestão de API. Assegurar que as equipas seguem as práticas estabelecidas que promovem a gestão consistente da API, a qualidade e a conformidade com as normas organizacionais.", "station.operating-guidelines.outcomes": "Práticas de governação da API estabelecidas", "station.operating-guidelines.outcomes.1": "Gestão e qualidade consistentes da API em toda a organização", "station.operating-guidelines.outcomes.2": "Conformidade com as normas organizacionais e as boas práticas", "station.operating-guidelines.outcomes.3": "Melhoria da visibilidade e do controlo das iniciativas API", "station.operating-guidelines.how_it_works": "Definir diretrizes operacionais baseadas nos Ciclos APIOps que descrevem os processos, as normas e as boas práticas para a gestão de API.", "station.operating-guidelines.how_it_works.1": "Estabelecer práticas de governação que garantam que as APIs são geridas de forma consistente, incluindo análises, auditorias e verificações de conformidade.", "station.operating-guidelines.how_it_works.2": "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação", "station.portfolio-management.title": "Gestão de portfólio - Gerir eficazmente o portfólio de API", "station.portfolio-management.description": "Gerir eficazmente a carteira de API para garantir o alinhamento com os objetivos de negócio e as iniciativas estratégicas.", "station.portfolio-management.why_it_matters": "O gestão eficaz do portfólio de APIs é essencial para garantir que as APIs se alinhem às metas comerciais e às iniciativas estratégicas. Esta estação fornece diretrizes para o gestão do portfólio de APIs, garantindo que as APIs sejam priorizadas, monitoradas e otimizadas para fornecer o máximo de valor.", "station.portfolio-management.apply_in_work": "Fornecer estruturas de gestão de carteiras, critérios de priorização e ferramentas de monitorização para a gestão de API. Assegurar que as equipas gerem eficazmente o portfólio de API, garantindo o alinhamento com os objetivos de negócio, as iniciativas estratégicas e a obtenção do máximo valor.", "station.portfolio-management.outcomes": "Estabelecimento de práticas de gestão de carteiras API", "station.portfolio-management.outcomes.1": "APIs alinhadas com objetivos de negócio e iniciativas estratégicas", "station.portfolio-management.outcomes.2": "Priorização e otimização de APIs com base no valor e no impacto", "station.portfolio-management.outcomes.3": "Melhoria da visibilidade e do controlo da carteira de API", "station.portfolio-management.how_it_works": "Definir práticas de gestão da carteira que descrevam os processos de gestão da carteira de API, incluindo a definição de prioridades, a monitorização e a otimização.", "station.budget-and-resource-management.title": "Orçamento e gestão de recursos - Otimizar os investimentos em API", "station.budget-and-resource-management.description": "Otimizar o orçamento e a gestão de recursos para as iniciativas API, a fim de garantir investimentos e atribuição de recursos eficazes.", "station.budget-and-resource-management.why_it_matters": "A gestão eficaz do orçamento e dos recursos é essencial para garantir que as iniciativas de API sejam bem financiadas e dotadas de recursos. Esta estação fornece diretrizes para otimizar a gestão do orçamento e dos recursos, assegurando que as iniciativas de API estão alinhadas com os objetivos de negócio e proporcionam o máximo valor.", "station.budget-and-resource-management.apply_in_work": "Fornecer estruturas de gestão orçamental, critérios de prioritização e ferramentas de monitorização para iniciativas de API. Assegurar que as equipas gerem eficazmente os orçamentos e os recursos, optimizando os investimentos no desenvolvimento e na gestão de API para obter o máximo valor.", "station.budget-and-resource-management.outcomes": "Práticas de gestão orçamental e de recursos estabelecidas para as iniciativas API", "station.budget-and-resource-management.outcomes.1": "Afetação efectiva de recursos às iniciativas API", "station.budget-and-resource-management.outcomes.2": "Investimentos optimizados no desenvolvimento e gestão de API", "station.budget-and-resource-management.outcomes.3": "Melhoria da visibilidade financeira e do controlo das iniciativas API", "station.budget-and-resource-management.how_it_works": "Definir práticas de gestão orçamental e de recursos que descrevam os processos de gestão de orçamentos e recursos para iniciativas de API.", "cycle.api-productization-cycle.station.api-product-strategy.title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "cycle.api-productization-cycle.station.api-product-strategy.why_it_matters": "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais.", "cycle.api-productization-cycle.station.api-product-strategy.apply_in_work": "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "cycle.api-productization-cycle.station.api-product-strategy.outcomes": "Uma proposta de valor e um público-alvo da API simples", "cycle.api-productization-cycle.station.api-product-strategy.outcomes.1": "Linguagem partilhada entre o produto, a conceção e a tecnologia", "cycle.api-productization-cycle.station.api-product-strategy.outcomes.2": "Um argumento sólido ou um caso para financiamento/aprovação", "cycle.api-productization-cycle.station.api-product-strategy.how_it_works": "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "cycle.api-productization-cycle.station.api-product-strategy.how_it_works.1": "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "cycle.api-productization-cycle.station.api-product-strategy.how_it_works.2": "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "cycle.api-productization-cycle.station.api-product-strategy.how_it_works.3": "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "cycle.api-productization-cycle.station.api-consumer-experience.title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "cycle.api-productization-cycle.station.api-consumer-experience.why_it_matters": "As APIs excelentes não funcionam apenas - elas são intuitivas. Quer o consumidor seja um programador interno, um parceiro externo ou um agente de IA, a sua experiência determina a adoção.\n\nSnum plano de experiência claro:\n- Grandes APIs ficam sem uso\n- As equipas perdem tempo a tentar adivinhar como utilizar a sua API\n- Os ciclos de feedback estão quebrados ou ausentes.\n\nEsta estação ajuda-o a ver a sua API através dos olhos dos seus consumidores.", "cycle.api-productization-cycle.station.api-consumer-experience.how_it_works": "Analise o Canvas da Proposta de Valor da API existente sob a perspectiva do consumidor da API. Mantenha as tarefas de negócios suportadas estáveis ​​e enriqueça os recursos que aliviam problemas e possibilitam ganhos com as preocupações do consumidor da API, para que elas possam orientar as decisões de conceção futuras.", "cycle.api-productization-cycle.station.api-consumer-experience.how_it_works.1": "Utilize o Canvas do Percurso do Cliente para a jornada do consumidor da API, desde a descoberta e avaliação até a integração, resolução de problemas e uso contínuo.", "cycle.api-productization-cycle.station.api-consumer-experience.how_it_works.2": "Utilize a jornada resultante para melhorar a integração, a documentação, o suporte e os ciclos de feedback para o consumidor da API.", "cycle.api-productization-cycle.station.api-consumer-experience.apply_in_work": "Fornecer diretrizes, ferramentas e mecanismos de feedback para compreender, analisar e melhorar a experiência interna e externa dos programadores e parceiros.", "cycle.api-productization-cycle.station.api-consumer-experience.outcomes": "Identifique e dê prioridade aos seus consumidores de API", "cycle.api-productization-cycle.station.api-consumer-experience.outcomes.1": "Definir o percurso da experiência API", "cycle.api-productization-cycle.station.api-consumer-experience.outcomes.2": "Planeamento da integração, documentação e feedback", "cycle.api-productization-cycle.station.api-consumer-experience.outcomes.3": "Melhorar a adoção através de empatia genuína + Experiência do Programador (DX)", "cycle.api-productization-cycle.station.api-platform-architecture.title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "cycle.api-productization-cycle.station.api-platform-architecture.why_it_matters": "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência.", "cycle.api-productization-cycle.station.api-platform-architecture.apply_in_work": "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "cycle.api-productization-cycle.station.api-platform-architecture.outcomes": "Corte APIs redundantes e reduza os custos da plataforma de nuvem", "cycle.api-productization-cycle.station.api-platform-architecture.outcomes.1": "Implementar uma governação consistente snum forte controlo do topo para a base", "cycle.api-productization-cycle.station.api-platform-architecture.outcomes.2": "Conceção para reutilização interna e escalabilidade externa", "cycle.api-productization-cycle.station.api-platform-architecture.how_it_works": "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "cycle.api-productization-cycle.station.api-platform-architecture.how_it_works.1": "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "cycle.api-productization-cycle.station.api-platform-architecture.how_it_works.2": "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "cycle.api-productization-cycle.station.api-platform-architecture.how_it_works.3": "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "cycle.api-productization-cycle.station.api-design.title": "Conceção da API - Conceber APIs que proporcionem valor", "cycle.api-productization-cycle.station.api-design.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.", "cycle.api-productization-cycle.station.api-design.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.", "cycle.api-productization-cycle.station.api-design.outcomes": "Conceção de API bem documentada e coerente", "cycle.api-productization-cycle.station.api-design.outcomes.1": "Contratos de interface da API reutilizáveis e validados", "cycle.api-productization-cycle.station.api-design.outcomes.2": "Desenhos alinhados com modelos de domínio e padrões de interação", "cycle.api-productization-cycle.station.api-design.outcomes.3": "Rastreabilidade da conceção ao valor de negócio", "cycle.api-productization-cycle.station.api-design.how_it_works": "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs.", "cycle.api-productization-cycle.station.api-design.how_it_works.1": "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.", "cycle.api-productization-cycle.station.api-design.how_it_works.2": "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.", "cycle.api-productization-cycle.station.api-design.how_it_works.3": "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.", "cycle.api-productization-cycle.station.api-design.how_it_works.4": "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.", "cycle.api-productization-cycle.station.api-design.how_it_works.5": "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.", "cycle.api-productization-cycle.station.api-design.how_it_works.6": "Aplique abordagens do tipo ‘contrato primeiro’ ou ‘design primeiro’ para capturar e validar o contrato de interface da API antes da implementação.", "cycle.api-productization-cycle.station.api-design.how_it_works.7": "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.", "cycle.api-productization-cycle.station.api-delivery.title": "Entrega da API - Fornecer APIs seguras e fiáveis", "cycle.api-productization-cycle.station.api-delivery.why_it_matters": "Mesmo os melhores conceções de API falham se a entrega for inconsistente. Esta estação assegura que as suas APIs são construídas com qualidade, testadas exaustivamente e implementadas de forma fiável - permitindo iterações mais rápidas e maior confiança.", "cycle.api-productization-cycle.station.api-delivery.apply_in_work": "Fornecer estruturas de codificação, bibliotecas e normas para a implementação de API. Implementar pipelines de CI/CD, estruturas de garantia de qualidade e ferramentas de automatização da disponibilização.", "cycle.api-productization-cycle.station.api-delivery.outcomes": "APIs implementadas utilizando estruturas e padrões testados", "cycle.api-productization-cycle.station.api-delivery.outcomes.1": "Pipelines de CI/CD fiáveis e automatizados", "cycle.api-productization-cycle.station.api-delivery.outcomes.2": "Testes funcionais e não funcionais integrados", "cycle.api-productization-cycle.station.api-delivery.outcomes.3": "Condutas de entrega seguras e conformes", "cycle.api-productization-cycle.station.api-delivery.how_it_works": "Utilize as Melhores Práticas de Desenvolvimento de API como orientação para implementar o contrato validado com frameworks e bibliotecas estabelecidos, garantindo que o resultado seja reutilizável e sustentável.", "cycle.api-productization-cycle.station.api-delivery.how_it_works.1": "Construa a implementação da API a partir do contrato validado usando frameworks, bibliotecas e padrões da equipa estabelecidos.", "cycle.api-productization-cycle.station.api-delivery.how_it_works.2": "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "cycle.api-productization-cycle.station.api-delivery.how_it_works.3": "Utilize pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "cycle.api-productization-cycle.station.api-delivery.how_it_works.4": "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "cycle.api-productization-cycle.station.api-delivery.how_it_works.5": "Utilize a lista de verificação de auditoria da API para garantir que a API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "cycle.api-productization-cycle.station.api-audit.title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "cycle.api-productization-cycle.station.api-audit.why_it_matters": "As APIs são produtos de longa duração e devem atender às expectativas de qualidade, consistência e conformidade. A auditoria conecta as decisões de conceção, a implementação e a prontidão operacional a padrões definidos, reduzindo o risco antes da exposição.", "cycle.api-productization-cycle.station.api-audit.apply_in_work": "Estabeleça um processo de auditoria consistente que avalie a prontidão da API em todas as etapas do ciclo de vida usando critérios, evidências e padrões definidos. Garanta que as lacunas sejam identificadas antecipadamente e resolvidas antes da publicação.", "cycle.api-productization-cycle.station.api-audit.outcomes": "As APIs cumprems normas internas e externas", "cycle.api-productization-cycle.station.api-audit.outcomes.1": "Documentação clara das decisões de conceção e implementação da API", "cycle.api-productization-cycle.station.api-audit.outcomes.2": "Segurança, desempenho e conformidade validados", "cycle.api-productization-cycle.station.api-audit.outcomes.3": "Redução do risco de problemas na produção", "cycle.api-productization-cycle.station.api-audit.how_it_works": "Realizar auditorias para garantir que as APIs cumprems normas organizacionais, técnicas e legais antes da publicação.", "cycle.api-productization-cycle.station.api-audit.how_it_works.1": "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas.", "cycle.api-productization-cycle.station.api-audit.how_it_works.2": "Colaborar com as equipas de governação e especialistas no domínio para garantir que as APIs estão prontas para produção.", "cycle.api-productization-cycle.station.api-publishing.title": "Publicação de API - Publique APIs com confiança", "cycle.api-productization-cycle.station.api-publishing.why_it_matters": "A publicação é mais do que a disponibilização - trata-se de capacidade de descoberta, acesso e suporte. Se as APIs não forem publicadas corretamente, não serão utilizadas, reutilizadas ou protegidas de forma eficaz.", "cycle.api-productization-cycle.station.api-publishing.apply_in_work": "Permitir que as APIs sejam publicadas no ambiente relevante e ter mecanismos claros de registo e acesso (por exemplo, chaves de API, OAuth, planos de subscrição), dependendo dos segmentos de consumidores de API e dos requisitos de segurança e conformidade.", "cycle.api-productization-cycle.station.api-publishing.outcomes": "APIs publicadas no ambiente correto (privado, parceiro, público)", "cycle.api-productization-cycle.station.api-publishing.outcomes.1": "Processos claros de integração e registo da API", "cycle.api-productization-cycle.station.api-publishing.outcomes.2": "Documentação, modelos e políticas de segurança disponíveis", "cycle.api-productization-cycle.station.api-publishing.outcomes.3": "APIs prontas para escala e governação", "cycle.api-productization-cycle.station.api-publishing.how_it_works": "Publicar APIs nos gateways e ambientes adequados para apoiar a reutilização por vários consumidores de API.", "cycle.api-productization-cycle.station.api-publishing.how_it_works.1": "Documentar a forma como os consumidores encontram e utilizam a API, incluindo processos de integração e registo.", "cycle.api-productization-cycle.station.api-publishing.how_it_works.2": "Garantir que os modelos de segurança, a configuração da porta de ligação e os termos legais sejam claros e acessíveis aos consumidores.", "cycle.api-productization-cycle.station.monitoring-and-improving.title": "Monitorização e melhoria - para valor API", "cycle.api-productization-cycle.station.monitoring-and-improving.why_it_matters": "A entrega da API não pára no lançamento. Sem monitorização, as equipas não podem melhorar a adoção, o desempenho ou o ROI. Esta estação garante que as APIs permaneçam úteis, seguras e evoluindo com as necessidades do negócio.", "cycle.api-productization-cycle.station.monitoring-and-improving.apply_in_work": "Criar quadros analíticos para acompanhar o desempenho e o envolvimento. Desenvolver ciclos de feedback, ferramentas de análise e estratégias de envolvimento para APIs.", "cycle.api-productization-cycle.station.monitoring-and-improving.outcomes": "Métricas de desempenho e utilização definidas e controladas", "cycle.api-productization-cycle.station.monitoring-and-improving.outcomes.1": "Ciclos de feedback do programador em vigor", "cycle.api-productization-cycle.station.monitoring-and-improving.outcomes.2": "Questões identificadas e tratadas continuamente", "cycle.api-productization-cycle.station.monitoring-and-improving.outcomes.3": "Iteração da API alinhada com as necessidades dos utilizadores", "cycle.api-productization-cycle.station.monitoring-and-improving.how_it_works": "Monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "cycle.api-productization-cycle.station.monitoring-and-improving.how_it_works.1": "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API.", "cycle.api-productization-cycle.station.monitoring-and-improving.how_it_works.2": "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua.", "cycle.capability-productization-cycle.station.api-product-strategy.title": "Estratégia", "cycle.capability-productization-cycle.station.api-product-strategy.why_it_matters": "O trabalho de integração e API salta muitas vezes demasiado cedo para um padrão técnico. Esta estação mantém a equipa focada na jornada de negócio, no significado do domínio, no valor, no potencial de reutilização, na propriedade e na viabilidade antes de selecionar APIs, eventos, ficheiros, streams, produtos de dados ou integração direta.", "cycle.capability-productization-cycle.station.api-product-strategy.apply_in_work": "Utilize canvases partilhados de jornada, domínio, proposta de valor e modelo de negócio para recolher requisitos independentes da tecnologia e decidir se a capacidade deve ser reutilizável.", "cycle.capability-productization-cycle.station.api-product-strategy.outcomes": "Uma declaração de oportunidade de capacidade independente da tecnologia", "cycle.capability-productization-cycle.station.api-product-strategy.outcomes.1": "Compreensão partilhada dos consumidores, produtores, conceitos de domínio e potencial de reutilização", "cycle.capability-productization-cycle.station.api-product-strategy.outcomes.2": "Uma proposta de valor e um modelo de negócio da capacidade antes da seleção da arquitetura", "cycle.capability-productization-cycle.station.api-product-strategy.how_it_works": "Mapeie a jornada do cliente ou parceiro que cria a necessidade da capacidade e revela tarefas, dores, ganhos, entradas, saídas e pontos de decisão.", "cycle.capability-productization-cycle.station.api-product-strategy.how_it_works.1": "Defina as entidades principais, atributos, relações, propriedade e regras de negócio que a capacidade deve respeitar.", "cycle.capability-productization-cycle.station.api-product-strategy.how_it_works.2": "Utilize o Canvas da Proposta de Valor da Capacidade para captar tarefas, ganhos, dores e funcionalidades reutilizáveis da capacidade para os consumidores, sem nomear a tecnologia de disponibilização demasiado cedo.", "cycle.capability-productization-cycle.station.api-product-strategy.how_it_works.3": "Utilize o Canvas do Modelo de Negócio da Capacidade para clarificar propriedade, parceiros, canais, custos, benefícios, suporte e expectativas de ciclo de vida da capacidade reutilizável.", "cycle.capability-productization-cycle.station.api-consumer-experience.title": "Requisitos e integração de consumidores", "cycle.capability-productization-cycle.station.api-consumer-experience.why_it_matters": "A arquitetura certa depende dos objetivos dos consumidores, das expectativas de integração, dos níveis de serviço, das necessidades de qualidade dos dados, da tolerância à mudança, da observabilidade, do suporte e das restrições dos produtores.", "cycle.capability-productization-cycle.station.api-consumer-experience.how_it_works": "Utilize o Canvas de Requisitos da Experiência do Consumidor para captar objetivos dos consumidores, disponibilidade, atualidade, volume, desempenho, qualidade dos dados, segurança, integração, mudança, observabilidade e expectativas de recuperação.", "cycle.capability-productization-cycle.station.api-consumer-experience.how_it_works.1": "Utilize orientação de integração para descrever como os consumidores vão encontrar, solicitar, testar, obter aprovação e começar a utilizar a capacidade.", "cycle.capability-productization-cycle.station.api-consumer-experience.how_it_works.2": "Utilize a jornada e os requisitos resultantes para melhorar a integração, a documentação, o suporte e os ciclos de feedback dos consumidores da capacidade.", "cycle.capability-productization-cycle.station.api-consumer-experience.apply_in_work": "Utilize orientação de experiência e integração de consumidores para tornar explícitas as expectativas de consumidores e produtores.", "cycle.capability-productization-cycle.station.api-consumer-experience.outcomes": "Requisitos dos consumidores e expectativas de integração documentados", "cycle.capability-productization-cycle.station.api-consumer-experience.outcomes.1": "Responsabilidades dos produtores e expectativas de suporte claras", "cycle.capability-productization-cycle.station.api-consumer-experience.outcomes.2": "Restrições relevantes para a arquitetura prontas para apoiar decisões", "cycle.capability-productization-cycle.station.api-consumer-experience.outcomes.3": "Adoção melhorada através de empatia com os consumidores, normas e clareza dos produtores", "cycle.capability-productization-cycle.station.api-platform-architecture.title": "Decisões de arquitetura e plataforma", "cycle.capability-productization-cycle.station.api-platform-architecture.why_it_matters": "As escolhas de arquitetura devem resultar de evidências sobre impacto de negócio, localizações, fronteiras de confiança, capacidade, latência, propriedade dos dados, consistência, operabilidade, segurança, privacidade, governação e custo.", "cycle.capability-productization-cycle.station.api-platform-architecture.apply_in_work": "Compare estilos de arquitetura viáveis com os requisitos recolhidos e documente o padrão selecionado e a respetiva justificação.", "cycle.capability-productization-cycle.station.api-platform-architecture.outcomes": "Uma escolha de arquitetura justificada", "cycle.capability-productization-cycle.station.api-platform-architecture.outcomes.1": "Riscos, localizações, capacidade, segurança, privacidade e restrições de operabilidade documentados", "cycle.capability-productization-cycle.station.api-platform-architecture.outcomes.2": "Justificação clara para API, evento, ficheiro, stream, produto de dados, integração direta ou disponibilização híbrida", "cycle.capability-productization-cycle.station.api-platform-architecture.how_it_works": "Utilize o Canvas de Impacto no Negócio para identificar riscos de disponibilidade, segurança e dados que influenciam as opções de arquitetura.", "cycle.capability-productization-cycle.station.api-platform-architecture.how_it_works.1": "Utilize o Canvas de Localizações para captar restrições geopolíticas, regulamentares, de rede, residência e fronteiras de confiança.", "cycle.capability-productization-cycle.station.api-platform-architecture.how_it_works.2": "Utilize o Canvas de Capacidade para captar volumes atuais e futuros, picos, latência, cache, limitação de pedidos e expectativas de escala.", "cycle.capability-productization-cycle.station.api-platform-architecture.how_it_works.3": "Utilize orientação de métricas e análise para definir como a capacidade escolhida será monitorizada e melhorada.", "cycle.capability-productization-cycle.station.api-design.title": "Conceção da solução e da interface", "cycle.capability-productization-cycle.station.api-design.why_it_matters": "Depois de conhecido o padrão de arquitetura, a conceção deve transformar os requisitos da capacidade em contratos de interface, interações, esquemas, regras de dados, expectativas de ciclo de vida e obrigações dos consumidores claros.", "cycle.capability-productization-cycle.station.api-design.apply_in_work": "Selecione os recursos de conceção adequados ao estilo de disponibilização escolhido e documente o contrato de interface antes da implementação.", "cycle.capability-productization-cycle.station.api-design.outcomes": "Um contrato de interface validado para o estilo de disponibilização selecionado", "cycle.capability-productization-cycle.station.api-design.outcomes.1": "Decisões consistentes sobre interação, dados, eventos, ficheiros, fluxos de trabalho ou contratos de API", "cycle.capability-productization-cycle.station.api-design.outcomes.2": "Rastreabilidade da conceção até aos requisitos da capacidade e dos consumidores", "cycle.capability-productization-cycle.station.api-design.outcomes.3": "Conceções alinhadas com modelos de domínio e padrões de interação", "cycle.capability-productization-cycle.station.api-design.how_it_works": "Reutilize o Canvas de Domínio para confirmar objetos de negócio, termos, regras e propriedade antes da conceção do contrato.", "cycle.capability-productization-cycle.station.api-design.how_it_works.1": "Utilize o Canvas de Interação para descrever como consumidores, sistemas ou utilizadores interagem com a capacidade.", "cycle.capability-productization-cycle.station.api-design.how_it_works.2": "Utilize recursos de conceção REST quando a interface selecionada for uma API REST.", "cycle.capability-productization-cycle.station.api-design.how_it_works.3": "Utilize recursos de Canvas de Eventos quando a interface selecionada for orientada por eventos.", "cycle.capability-productization-cycle.station.api-design.how_it_works.4": "Utilize recursos de conceção GraphQL quando a interface selecionada for GraphQL.", "cycle.capability-productization-cycle.station.api-design.how_it_works.5": "Utilize os princípios de conceção e a orientação de estilo para alinhar decisões de conceção com regras partilhadas e permitir validação de auditoria consistente.", "cycle.capability-productization-cycle.station.api-design.how_it_works.6": "Aplique abordagens contract-first ou design-first para captar e validar o contrato de interface antes da implementação.", "cycle.capability-productization-cycle.station.api-design.how_it_works.7": "Utilize a lista de verificação de auditoria para garantir que a conceção cumpre requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "cycle.capability-productization-cycle.station.api-delivery.title": "Entrega e operações", "cycle.capability-productization-cycle.station.api-delivery.why_it_matters": "Uma capacidade reutilizável precisa de entrega e operações fiáveis, quer se torne uma API, stream de eventos, troca de ficheiros, produto de dados ou integração direta.", "cycle.capability-productization-cycle.station.api-delivery.apply_in_work": "Aplique orientação de entrega, testes, CI/CD, operações e segurança ao estilo de disponibilização escolhido.", "cycle.capability-productization-cycle.station.api-delivery.outcomes": "Uma capacidade entregue e alinhada com o contrato de interface validado", "cycle.capability-productization-cycle.station.api-delivery.outcomes.1": "Testes, disponibilização e controlos de ambiente automatizados", "cycle.capability-productization-cycle.station.api-delivery.outcomes.2": "Práticas de segurança, operações e qualidade adequadas ao padrão escolhido", "cycle.capability-productization-cycle.station.api-delivery.outcomes.3": "Controlos de entrega e disponibilização rastreáveis", "cycle.capability-productization-cycle.station.api-delivery.how_it_works": "Utilize boas práticas de desenvolvimento para implementar o contrato de interface validado com frameworks, bibliotecas e normas da equipa estabelecidos.", "cycle.capability-productization-cycle.station.api-delivery.how_it_works.1": "Construa a implementação a partir do contrato de interface validado, usando frameworks, bibliotecas e normas da equipa estabelecidos.", "cycle.capability-productization-cycle.station.api-delivery.how_it_works.2": "Utilize orientação de testes para verificar funcionalidade, qualidade dos dados, compatibilidade, segurança, desempenho, resiliência e expectativas de recuperação.", "cycle.capability-productization-cycle.station.api-delivery.how_it_works.3": "Utilize orientação de CI/CD para automatizar construção, testes, disponibilização, configuração e rastreabilidade.", "cycle.capability-productization-cycle.station.api-delivery.how_it_works.4": "Utilize orientação de segurança para proteger dados, acesso, credenciais e fronteiras da plataforma.", "cycle.capability-productization-cycle.station.api-delivery.how_it_works.5": "Utilize a lista de verificação de auditoria para garantir que a solução cumpre requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "cycle.capability-productization-cycle.station.api-audit.title": "Garantia de qualidade e prontidão", "cycle.capability-productization-cycle.station.api-audit.why_it_matters": "As capacidades reutilizáveis criam riscos operacionais, de dados, segurança, privacidade, conformidade e impacto nos consumidores. As verificações de prontidão reduzem surpresas antes da publicação ou utilização em produção.", "cycle.capability-productization-cycle.station.api-audit.apply_in_work": "Utilize recursos de auditoria e conformidade para verificar que a capacidade está pronta para disponibilização controlada e reutilização.", "cycle.capability-productization-cycle.station.api-audit.outcomes": "Prontidão para disponibilização e reutilização documentada", "cycle.capability-productization-cycle.station.api-audit.outcomes.1": "Lacunas e mitigações conhecidas antes da publicação", "cycle.capability-productization-cycle.station.api-audit.outcomes.2": "Evidências para aprovação de governação, conformidade, suporte e operações", "cycle.capability-productization-cycle.station.api-audit.outcomes.3": "Risco reduzido de problemas em produção", "cycle.capability-productization-cycle.station.api-audit.how_it_works": "Utilize a lista de verificação de auditoria como checklist de qualidade reutilizável para contrato de interface, documentação, segurança, desempenho e prontidão de conformidade.", "cycle.capability-productization-cycle.station.api-audit.how_it_works.1": "Utilize checklists, linters e ferramentas de teste para verificar consistência e conformidade com normas.", "cycle.capability-productization-cycle.station.api-audit.how_it_works.2": "Colabore com equipas de governação e especialistas de domínio para garantir que a capacidade está pronta para produção.", "cycle.capability-productization-cycle.station.api-publishing.title": "Publicação e capacitação", "cycle.capability-productization-cycle.station.api-publishing.why_it_matters": "As capacidades reutilizáveis só criam valor quando os consumidores as conseguem encontrar, compreender o respetivo contrato de interface e expectativas de serviço, solicitar acesso e saber quem é responsável pelo suporte e pelas decisões de ciclo de vida.", "cycle.capability-productization-cycle.station.api-publishing.apply_in_work": "Publique propriedade, documentação, integração, contactos de suporte, expectativas de serviço, estado de ciclo de vida e caminhos para pedidos de acesso.", "cycle.capability-productization-cycle.station.api-publishing.outcomes": "Uma capacidade reutilizável detetável", "cycle.capability-productization-cycle.station.api-publishing.outcomes.1": "Expectativas claras de integração, acesso, suporte e serviço", "cycle.capability-productization-cycle.station.api-publishing.outcomes.2": "Informação de ciclo de vida e propriedade disponível para consumidores e equipas de governação", "cycle.capability-productization-cycle.station.api-publishing.outcomes.3": "Consumidores capacitados para utilizar e reutilizar a capacidade", "cycle.capability-productization-cycle.station.api-publishing.how_it_works": "Publique informação sobre a capacidade nos catálogos, portais, gateways ou ambientes adequados para apoiar a reutilização por vários consumidores.", "cycle.capability-productization-cycle.station.api-publishing.how_it_works.1": "Documente como os consumidores encontram e utilizam a capacidade, incluindo processos de integração e registo.", "cycle.capability-productization-cycle.station.api-publishing.how_it_works.2": "Garanta que os modelos de segurança, a configuração de acesso e os termos legais são claros e acessíveis aos consumidores.", "cycle.capability-productization-cycle.station.monitoring-and-improving.title": "Monitorização e melhoria", "cycle.capability-productization-cycle.station.monitoring-and-improving.why_it_matters": "As capacidades precisam de feedback contínuo para permanecerem fiáveis, valiosas, rentáveis e reutilizáveis à medida que consumidores, sistemas, dados e plataformas mudam.", "cycle.capability-productization-cycle.station.monitoring-and-improving.apply_in_work": "Utilize práticas de métricas, análise e envolvimento para melhorar a capacidade ao longo do tempo.", "cycle.capability-productization-cycle.station.monitoring-and-improving.outcomes": "Saúde e valor da capacidade medidos", "cycle.capability-productization-cycle.station.monitoring-and-improving.outcomes.1": "Backlog de melhorias informado por feedback operacional e dos consumidores", "cycle.capability-productization-cycle.station.monitoring-and-improving.outcomes.2": "Sinais de reutilização, fiabilidade, qualidade dos dados e custo disponíveis para os responsáveis", "cycle.capability-productization-cycle.station.monitoring-and-improving.outcomes.3": "Melhoria contínua alinhada com as necessidades dos consumidores", "cycle.capability-productization-cycle.station.monitoring-and-improving.how_it_works": "Utilize orientação de métricas e análise para definir medidas de utilização da capacidade, fiabilidade, qualidade dos dados, custo, adoção e valor para os consumidores.", "cycle.capability-productization-cycle.station.monitoring-and-improving.how_it_works.1": "Analise métricas de utilização e incorpore feedback dos consumidores nas iterações da capacidade.", "cycle.capability-productization-cycle.station.monitoring-and-improving.how_it_works.2": "Estabeleça o hábito de rever métricas e planear atividades de melhoria contínua.", "resource.api-community-engagement-strategies.title": "Estratégias de envolvimento da comunidade API", "resource.api-community-engagement-strategies.description": "Um manual para promover a adoção de APIs, cultivando comunidades através de conteúdos, canais de apoio, ciclos de feedback e estratégias de envolvimento social.", "resource.api-community-engagement-strategies.outcomes": "Melhor compreensão dos princípios das estratégias de envolvimento da comunidade da API", "resource.api-community-engagement-strategies.outcomes.1": "Abordagem normalizada utilizando as estratégias de envolvimento da comunidade da API", "resource.api-community-engagement-strategies.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.api-community-engagement-strategies.steps": "Desenvolver estratégias de marketing para promover as APIs junto de públicos-alvo, incluindo redes sociais, blogues e webinars.", "resource.api-community-engagement-strategies.steps.1": "Criar materiais promocionais (por exemplo, estudos de casos, histórias de sucesso) que realcem o valor e as vantagens das APIs.", "resource.api-community-engagement-strategies.steps.2": "Criar materiais educativos (por exemplo, tutoriais, documentação) que expliquem as características, as vantagens e os padrões de utilização da API.", "resource.api-community-engagement-strategies.steps.3": "Interagir com os utilizadores da API através de ciclos de feedback, canais de apoio e fóruns da comunidade para compreender as suas necessidades e melhorar a adoção da API.", "resource.api-community-engagement-strategies.steps.4": "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API.", "resource.api-community-engagement-strategies.tips": "Personalize as estratégias de envolvimento da comunidade de API ao seu domínio", "resource.api-community-engagement-strategies.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.api-compliance-best-practices.title": "Boas práticas de conformidade da API", "resource.api-compliance-best-practices.description": "Garantir que as APIs cumprem conformidade legal, regulamentar e interna através de documentação, controlos e validações automatizadas.", "resource.api-compliance-best-practices.outcomes": "Melhor compreensão dos princípios das boas práticas de conformidade da API", "resource.api-compliance-best-practices.outcomes.1": "Abordagem normalizada utilizando as Melhores Práticas de Conformidade da API", "resource.api-compliance-best-practices.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.api-compliance-best-practices.steps": "Documentar as medidas de conformidade e garantir que são comunicadas às partes interessadas e aos utilizadores.", "resource.api-compliance-best-practices.steps.1": "Implementar medidas para garantir que as APIs cumprem estes requisitos, incluindo encriptação de dados, controlos de acesso e pistas de auditoria.", "resource.api-compliance-best-practices.steps.2": "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas.", "resource.api-compliance-best-practices.tips": "Personalizar as Melhores Práticas de Conformidade de API ao seu domínio", "resource.api-compliance-best-practices.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.api-development-best-practices.title": "Boas práticas de desenvolvimento de API", "resource.api-development-best-practices.description": "Orientações de implementação para transformar um contrato de interface da API validado numa base de código de API consistente e sustentável, utilizando bibliotecas padrão, padrões reutilizáveis e fluxos de trabalho de desenvolvimento alinhados.", "resource.api-development-best-practices.outcomes": "Melhor compreensão dos princípios das boas práticas de desenvolvimento de API", "resource.api-development-best-practices.outcomes.1": "Abordagem normalizada utilizando as boas práticas de desenvolvimento de API", "resource.api-development-best-practices.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.api-development-best-practices.steps": "Aplique essas práticas ao contrato de interface da API validado e ao plano de implementação antes do início da codificação.", "resource.api-development-best-practices.steps.1": "Utilize frameworks, bibliotecas e padrões de codificação estabelecidos para implementar o contrato de forma consistente e sustentável.", "resource.api-development-best-practices.tips": "Utilize este recurso como orientação de implementação e lente de revisão, em vez de como um artefato independente obrigatório", "resource.api-development-best-practices.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.api-metrics-and-analytics.title": "Métricas e análise de API", "resource.api-metrics-and-analytics.description": "Um recurso para definir, recolher e analisar o desempenho da API e os dados de utilização para alinhar os KPIs técnicos com os resultados de negócio.", "resource.api-metrics-and-analytics.outcomes": "Melhor compreensão dos princípios de métrica e análise de API", "resource.api-metrics-and-analytics.outcomes.1": "Abordagem normalizada utilizando métricas e análise de API", "resource.api-metrics-and-analytics.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.api-metrics-and-analytics.steps": "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "resource.api-metrics-and-analytics.steps.1": "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "resource.api-metrics-and-analytics.steps.2": "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação", "resource.api-metrics-and-analytics.tips": "Personalizar as métricas e análise de API ao seu domínio", "resource.api-metrics-and-analytics.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.api-onboarding-best-practices.title": "Boas práticas de integração de API", "resource.api-onboarding-best-practices.description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "resource.api-onboarding-best-practices.outcomes": "Melhor compreensão dos princípios das boas práticas de integração de API", "resource.api-onboarding-best-practices.outcomes.1": "Abordagem normalizada utilizando as boas práticas de integração de API", "resource.api-onboarding-best-practices.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.api-onboarding-best-practices.steps": "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "resource.api-onboarding-best-practices.steps.1": "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "resource.api-onboarding-best-practices.steps.2": "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo.", "resource.api-onboarding-best-practices.tips": "Personalizar as boas práticas de integração de API ao seu domínio", "resource.api-onboarding-best-practices.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.api-portfolio-management-guidelines.title": "Diretrizes de gestão da carteira API", "resource.api-portfolio-management-guidelines.description": "Um guia para gerir estrategicamente o conjunto de APIs de uma organização - priorizando APIs, alocando recursos e monitorando o desempenho ao longo de todo o ciclo de vida.", "resource.api-portfolio-management-guidelines.outcomes": "Melhor compreensão dos princípios orientadores da gestão de carteiras API", "resource.api-portfolio-management-guidelines.outcomes.1": "Abordagem normalizada utilizando as diretrizes de gestão de portfólio da API", "resource.api-portfolio-management-guidelines.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.api-portfolio-management-guidelines.steps": "Definir práticas de gestão da carteira que descrevam os processos de gestão da carteira de API, incluindo a definição de prioridades, a monitorização e a otimização.", "resource.api-portfolio-management-guidelines.steps.1": "Definir práticas de gestão orçamental e de recursos que descrevam os processos de gestão de orçamentos e recursos para iniciativas de API.", "resource.api-portfolio-management-guidelines.steps.2": "Estabelecer critérios para avaliar e dar prioridade às dotações orçamentais com base no valor de negócio, no impacto e no alinhamento com as iniciativas estratégicas.", "resource.api-portfolio-management-guidelines.steps.3": "Monitorizar a carteira de APIs para garantir que as APIs estão a fornecer valor, a cumprir as expectativas de desempenho e a alinhar-se com os objetivos de negócio.", "resource.api-portfolio-management-guidelines.tips": "Personalizar as Diretrizes de Gestão de Portfólio API ao seu domínio", "resource.api-portfolio-management-guidelines.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.api-security-best-practices.title": "Boas práticas de segurança da API", "resource.api-security-best-practices.description": "Um conjunto de controlos acionáveis para proteger APIs, incluindo autenticação, autorização, encriptação, limitação de taxas e verificações de conformidade ao nível do pipeline.", "resource.api-security-best-practices.outcomes": "Melhor compreensão dos princípios das boas práticas de segurança da API", "resource.api-security-best-practices.outcomes.1": "Abordagem normalizada utilizando as boas práticas de segurança da API", "resource.api-security-best-practices.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.api-security-best-practices.steps": "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "resource.api-security-best-practices.steps.1": "Implemente medidas de segurança como autenticação, autorização, encriptação e limitação de taxas para proteger as APIs de ameaças.", "resource.api-security-best-practices.steps.2": "Implementar verificações de segurança automatizadas e validações de conformidade no pipeline CI/CD para garantir que as APIs são seguras e compatíveis.", "resource.api-security-best-practices.tips": "Personalize as boas práticas de segurança de API ao seu domínio", "resource.api-security-best-practices.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.api-team-structure-guidelines.title": "Diretrizes da estrutura da equipa API", "resource.api-team-structure-guidelines.description": "Orientação organizacional para a definição de funções e responsabilidades nas equipas de API para garantir clareza, colaboração e responsabilidade.", "resource.api-team-structure-guidelines.outcomes": "Melhor compreensão dos princípios orientadores da estrutura da equipa API", "resource.api-team-structure-guidelines.outcomes.1": "Abordagem normalizada utilizando as Diretrizes da Estrutura da Equipa API", "resource.api-team-structure-guidelines.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.api-team-structure-guidelines.steps": "Definir estruturas de equipa e funções para equipas de API, incluindo proprietários de produtos de API, programadores, arquitectos e operações.", "resource.api-team-structure-guidelines.tips": "Personalizar as Diretrizes da estrutura da equipa API ao seu domínio", "resource.api-team-structure-guidelines.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.api-testing-best-practices.title": "Boas práticas de teste de API", "resource.api-testing-best-practices.description": "Diretrizes para a implementação de testes automatizados funcionais, de desempenho e de segurança ao longo do ciclo de vida da API.", "resource.api-testing-best-practices.outcomes": "Melhor compreensão dos princípios das boas práticas de teste de API", "resource.api-testing-best-practices.outcomes.1": "Abordagem normalizada utilizando as boas práticas de teste de API", "resource.api-testing-best-practices.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.api-testing-best-practices.steps": "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "resource.api-testing-best-practices.steps.1": "Integrar testes funcionais e não funcionais no pipeline CI/CD para garantir que as APIs cumprems normas de qualidade.", "resource.api-testing-best-practices.steps.2": "Utilizar ferramentas de teste automatizadas para validar a funcionalidade, a segurança e o desempenho da API.", "resource.api-testing-best-practices.tips": "Personalize as boas práticas de teste de API ao seu domínio", "resource.api-testing-best-practices.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.api-training-programs.title": "Programas de formação API", "resource.api-training-programs.description": "Um roteiro para melhorar as competências das equipas com percursos de aprendizagem estruturados em design, governação, desempenho e segurança de API.", "resource.api-training-programs.outcomes": "Melhor compreensão dos princípios dos programas de formação API", "resource.api-training-programs.outcomes.1": "Abordagem normalizada utilizando Programas de Formação API", "resource.api-training-programs.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.api-training-programs.steps": "Identificar as principais competências e áreas de conhecimento da API que precisam de ser melhoradas, como a conceção, a segurança e o desempenho da API.", "resource.api-training-programs.steps.1": "Incentivar a aprendizagem contínua através de cursos em linha, certificações e envolvimento da comunidade.", "resource.api-training-programs.steps.2": "Fornecer formação e recursos para ajudar as equipas a adotar uma mentalidade de prioridade à API e a compreender as vantagens das APIs.", "resource.api-training-programs.steps.3": "Fornecer programas de formação, workshops e recursos para ajudar as equipas a melhorar as suas competências e conhecimentos em matéria de API.", "resource.api-training-programs.tips": "Personalizar os programas de formação API ao seu domínio", "resource.api-training-programs.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.api-versioning-best-practices.title": "Boas práticas de controlo de versões da API", "resource.api-versioning-best-practices.description": "Estratégias para introduzir, manter e retirar versões de API, preservando a compatibilidade com versões anteriores e a confiança dos utilizadores.", "resource.api-versioning-best-practices.outcomes": "Melhor compreensão dos princípios das boas práticas de controlo de versões da API", "resource.api-versioning-best-practices.outcomes.1": "Abordagem normalizada utilizando as boas práticas de controlo de versões da API", "resource.api-versioning-best-practices.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.api-versioning-best-practices.steps": "Definir estratégias de controlo de versões para as APIs para gerir as alterações e garantir a compatibilidade com as versões anteriores.", "resource.api-versioning-best-practices.tips": "Personalizar as boas práticas de controlo de versões de API ao seu domínio", "resource.api-versioning-best-practices.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.apiops-CI-CD-for-apis.title": "APIOps CI/CD para APIs", "resource.apiops-CI-CD-for-apis.description": "Orientação de disponibilização que integra tarefas do ciclo de vida da API - design, teste, governação - em pipelines de integração e entrega contínuas.", "resource.apiops-CI-CD-for-apis.outcomes": "Melhor compreensão dos princípios de CI/CD para APIs", "resource.apiops-CI-CD-for-apis.outcomes.1": "Abordagem normalizada utilizando CI/CD para APIs", "resource.apiops-CI-CD-for-apis.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.apiops-CI-CD-for-apis.steps": "Utilizar pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "resource.apiops-CI-CD-for-apis.steps.1": "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "resource.apiops-CI-CD-for-apis.steps.2": "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "resource.apiops-CI-CD-for-apis.steps.3": "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua.", "resource.apiops-CI-CD-for-apis.tips": "Personalize as APIs CI/CD For ao seu domínio", "resource.apiops-CI-CD-for-apis.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.competitor-analysis-template.title": "Modelo de análise da concorrência", "resource.competitor-analysis-template.description": "Uma folha de cálculo estruturada para comparar as suas ofertas de API com a concorrência, mapeando os pontos fortes, os pontos fracos e os diferenciadores de valor.", "resource.competitor-analysis-template.outcomes": "Melhor compreensão dos princípios do modelo de análise da concorrência", "resource.competitor-analysis-template.outcomes.1": "Abordagem normalizada utilizando o modelo de análise da concorrência", "resource.competitor-analysis-template.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.competitor-analysis-template.steps": "Efetuar uma análise da concorrência para identificar os principais concorrentes e as suas ofertas de API.", "resource.competitor-analysis-template.steps.1": "Analisar as APIs da concorrência para compreender os seus pontos fortes, fracos e pontos de venda únicos.", "resource.competitor-analysis-template.tips": "Personalizar o modelo de análise da concorrência ao seu domínio", "resource.competitor-analysis-template.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.contract-first-design.title": "Primeira conceção do contrato", "resource.contract-first-design.description": "Uma diretriz que defende abordagens API-first utilizando contratos formais (por exemplo, OpenAPI) para alinhar as partes interessadas antes do desenvolvimento.", "resource.contract-first-design.outcomes": "Melhor compreensão dos princípios de conceção da primeira fase do contrato", "resource.contract-first-design.outcomes.1": "Abordagem normalizada utilizando a conceção orientada por contrato", "resource.contract-first-design.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.contract-first-design.steps": "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "resource.contract-first-design.steps.1": "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "resource.contract-first-design.steps.2": "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar.", "resource.contract-first-design.tips": "Personalize a conceção do Contract First ao seu domínio", "resource.contract-first-design.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.cross-functional-collaboration-best-practices.title": "Boas práticas de colaboração interfuncional", "resource.cross-functional-collaboration-best-practices.description": "Práticas para facilitar a comunicação e o alinhamento entre as equipas de negócio e técnicas ao planear ou fornecer APIs.", "resource.cross-functional-collaboration-best-practices.outcomes": "Melhor compreensão dos princípios das boas práticas de colaboração interfuncional", "resource.cross-functional-collaboration-best-practices.outcomes.1": "Abordagem normalizada utilizando as boas práticas de colaboração interfuncional", "resource.cross-functional-collaboration-best-practices.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.cross-functional-collaboration-best-practices.steps": "Incentivar a colaboração multifuncional entre equipas de API, unidades empresariais e partes interessadas para alinhar as iniciativas de API com os objetivos empresariais.", "resource.cross-functional-collaboration-best-practices.tips": "Personalize as Melhores Práticas de Colaboração Interfuncional ao seu domínio", "resource.cross-functional-collaboration-best-practices.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.data-privacy-guidelines.title": "Diretrizes de privacidade de dados", "resource.data-privacy-guidelines.description": "Considerações de design para garantir que as APIs cumprem os regulamentos de proteção de dados, como o RGPD, através de anonimização e controlos de acesso.", "resource.data-privacy-guidelines.outcomes": "Melhor compreensão dos princípios das diretrizes relativas à privacidade dos dados", "resource.data-privacy-guidelines.outcomes.1": "Abordagem normalizada utilizando as Diretrizes de Privacidade de Dados", "resource.data-privacy-guidelines.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.data-privacy-guidelines.steps": "Garantir a privacidade dos dados dos utilizadores através da implementação de medidas de proteção de dados, como a anonimização e os controlos de acesso.", "resource.data-privacy-guidelines.tips": "Personalizar as Diretrizes de Privacidade de Dados ao seu domínio", "resource.data-privacy-guidelines.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.domain-canvas.title": "Canvas de Domínio", "resource.domain-canvas.description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "resource.domain-canvas.outcomes": "Melhor compreensão dos princípios do domínio canvas", "resource.domain-canvas.outcomes.1": "Abordagem normalizada utilizando o Canvas de Domínio", "resource.domain-canvas.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.domain-canvas.steps": "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs.", "resource.domain-canvas.tips": "Personalizar o Canvas de Domínio ao seu domínio", "resource.domain-canvas.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.ecosystem-vision-template.title": "Modelo de visão do ecossistema", "resource.ecosystem-vision-template.description": "Uma ferramenta de planeamento estratégico para definir o ecossistema API, incluindo parceiros-alvo, cadeias de valor e oportunidades de integração.", "resource.ecosystem-vision-template.outcomes": "Melhor compreensão dos princípios do modelo de visão do ecossistema", "resource.ecosystem-vision-template.outcomes.1": "Abordagem normalizada utilizando o Modelo de Visão do Ecossistema", "resource.ecosystem-vision-template.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.ecosystem-vision-template.steps": "Realizar estudos de mercado para identificar tendências, oportunidades e ameaças no panorama das APIs.", "resource.ecosystem-vision-template.steps.1": "Identificar os principais parceiros e intervenientes do ecosistema que irão beneficiar ou contribuir para o ecosistema.", "resource.ecosystem-vision-template.steps.2": "Identifique as lacunas no mercado que as suas APIs podem preencher, com base nas ofertas da concorrência.", "resource.ecosystem-vision-template.steps.3": "Identifique potenciais parceiros cujas APIs possam melhorar as suas capacidades de API e a sua proposta de valor.", "resource.ecosystem-vision-template.steps.4": "Desenvolva uma estratégia de diferenciação que destaque as características e benefícios únicos das suas APIs.", "resource.ecosystem-vision-template.steps.5": "Defina a visão do ecossistema para as suas APIs, incluindo a forma como estas irão interagir com outros sistemas e plataformas.", "resource.ecosystem-vision-template.steps.6": "Conceber APIs para permitir uma integração e colaboração perfeitas no ecossistema.", "resource.ecosystem-vision-template.tips": "Personalizar o modelo de visão do ecossistema ao seu domínio", "resource.ecosystem-vision-template.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.industry-standards-and-best-practices.title": "Normas e boas práticas do sector", "resource.industry-standards-and-best-practices.description": "Um recurso de referência para alinhar a conceção e a operação da API com estruturas e especificações amplamente reconhecidas do sector.", "resource.industry-standards-and-best-practices.outcomes": "Melhor compreensão das normas do sector e dos princípios das boas práticas", "resource.industry-standards-and-best-practices.outcomes.1": "Abordagem normalizada utilizando as normas e as boas práticas do sector", "resource.industry-standards-and-best-practices.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.industry-standards-and-best-practices.steps": "Identificar as normas e as boas práticas do sector para garantir que as APIs são competitivas e estão em conformidade.", "resource.industry-standards-and-best-practices.tips": "Personalize os padrões e as boas práticas da indústria ao seu domínio", "resource.industry-standards-and-best-practices.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.partner-integration-guidelines.title": "Diretrizes de integração de parceiros", "resource.partner-integration-guidelines.description": "Listas de verificação de integração e padrões de comunicação para gerir os aspectos técnicos e legais das relações com APIs de terceiros.", "resource.partner-integration-guidelines.outcomes": "Melhor compreensão dos princípios das diretrizes de integração de parceiros", "resource.partner-integration-guidelines.outcomes.1": "Abordagem normalizada utilizando as Diretrizes de Integração de Parceiros", "resource.partner-integration-guidelines.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.partner-integration-guidelines.steps": "Estabelecer processos de integração e orientações para colaborar com os parceiros, incluindo a integração técnica, a partilha de dados e o apoio.", "resource.partner-integration-guidelines.steps.1": "Monitorize o desempenho e a conformidade da API do parceiro para garantir a fiabilidade e o alinhamento com a sua estratégia de API.", "resource.partner-integration-guidelines.tips": "Personalizar as Diretrizes de Integração de Parceiros ao seu domínio", "resource.partner-integration-guidelines.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.role-communication-best-practices.title": "Boas práticas de comunicação de funções", "resource.role-communication-best-practices.description": "Ferramentas para definir e documentar quem é responsável por quê nas iniciativas de API, garantindo que as transferências e a responsabilidade sejam claras.", "resource.role-communication-best-practices.outcomes": "Melhor compreensão dos princípios das boas práticas de comunicação de funções", "resource.role-communication-best-practices.outcomes.1": "Abordagem normalizada utilizando as boas práticas de comunicação de funções", "resource.role-communication-best-practices.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.role-communication-best-practices.steps": "Estabelecer responsabilidades claras para cada função, incluindo a conceção, o desenvolvimento, os testes e as operações da API.", "resource.role-communication-best-practices.steps.1": "Assegurar que as funções e responsabilidades são comunicadas a todos os membros da equipa e partes interessadas para garantir o alinhamento.", "resource.role-communication-best-practices.tips": "Personalizar as Melhores Práticas de Comunicação de Funções ao seu domínio", "resource.role-communication-best-practices.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.scalable-infrastructure-best-practices.title": "Boas práticas de infraestrutura escalável", "resource.scalable-infrastructure-best-practices.description": "Orientação arquitetónica para garantir que as APIs são implementadas em infra-estruturas que podem lidar elasticamente com picos de utilização e crescimento.", "resource.scalable-infrastructure-best-practices.outcomes": "Melhor compreensão dos princípios das boas práticas de infra-estruturas escaláveis", "resource.scalable-infrastructure-best-practices.outcomes.1": "Abordagem normalizada utilizando as Melhores Práticas de Infraestrutura Escalável", "resource.scalable-infrastructure-best-practices.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.scalable-infrastructure-best-practices.steps": "Conceber a infraestrutura da API para ser escalável e resiliente, utilizando padrões e tecnologias nativos da nuvem.", "resource.scalable-infrastructure-best-practices.steps.1": "Monitorizar o desempenho e a capacidade da infraestrutura para garantir que esta consegue dar resposta à crescente procura.", "resource.scalable-infrastructure-best-practices.tips": "Personalize as Melhores Práticas de Infraestrutura Escalável ao seu domínio", "resource.scalable-infrastructure-best-practices.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.service-agreement-template.title": "Modelo de contrato de serviço", "resource.service-agreement-template.description": "Um formato de acordo personalizável que define expectativas, SLAs, responsabilidades e termos de acesso para o consumo de API.", "resource.service-agreement-template.outcomes": "Melhor compreensão dos princípios do modelo de contrato de prestação de serviços", "resource.service-agreement-template.outcomes.1": "Abordagem normalizada utilizando o modelo de contrato de serviços", "resource.service-agreement-template.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.service-agreement-template.steps": "Defina acordos de serviço que descrevam as expectativas, os níveis de serviço e as responsabilidades de cada API.", "resource.service-agreement-template.steps.1": "Utilize formatos normalizados para criar contratos de serviço legíveis por máquina que sejam fáceis de partilhar e validar.", "resource.service-agreement-template.steps.2": "Assegurar que os acordos de serviço são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza.", "resource.service-agreement-template.tips": "Personalizar o modelo de contrato de serviço ao seu domínio", "resource.service-agreement-template.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.stakeholder-engagement-best-practices.title": "Boas práticas de envolvimento das partes interessadas", "resource.stakeholder-engagement-best-practices.description": "Tácticas de envolvimento para alinhar as partes interessadas internas e externas em torno dos objetivos, valor e governação partilhados da API.", "resource.stakeholder-engagement-best-practices.outcomes": "Melhor compreensão dos princípios das boas práticas de envolvimento das partes interessadas", "resource.stakeholder-engagement-best-practices.outcomes.1": "Abordagem normalizada utilizando as Melhores Práticas de Envolvimento das Partes Interessadas", "resource.stakeholder-engagement-best-practices.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.stakeholder-engagement-best-practices.steps": "Envolver as partes interessadas para garantir o alinhamento e o apoio às iniciativas da API.", "resource.stakeholder-engagement-best-practices.tips": "Personalize as Melhores Práticas de Envolvimento das Partes Interessadas ao seu domínio", "resource.stakeholder-engagement-best-practices.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.test-automation-frameworks.title": "Estruturas de automatização de testes", "resource.test-automation-frameworks.description": "Ferramentas e padrões recomendados para automatizar testes de contrato, regressão e integração de API em vários ambientes.", "resource.test-automation-frameworks.outcomes": "Melhor compreensão dos princípios das estruturas de automatização de testes", "resource.test-automation-frameworks.outcomes.1": "Abordagem normalizada utilizando estruturas de automatização de testes", "resource.test-automation-frameworks.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.test-automation-frameworks.steps": "Implementar estruturas de automatização de testes que apoiem os testes de contrato, os testes de integração e os testes de ponta a ponta.", "resource.test-automation-frameworks.tips": "Personalizar as estruturas de automatização de testes ao seu domínio", "resource.test-automation-frameworks.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.vendor-management-best-practices.title": "Boas práticas de gestão de fornecedores", "resource.vendor-management-best-practices.description": "Estrutura para avaliar e gerir fornecedores externos de API e integrações de terceiros com base no risco, desempenho e conformidade.", "resource.vendor-management-best-practices.outcomes": "Melhor compreensão dos princípios das boas práticas de gestão de fornecedores", "resource.vendor-management-best-practices.outcomes.1": "Abordagem normalizada utilizando as boas práticas de gestão de fornecedores", "resource.vendor-management-best-practices.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.vendor-management-best-practices.steps": "Estabelecer processos de gestão de fornecedores para avaliar, integrar e monitorizar fornecedores de API de terceiros.", "resource.vendor-management-best-practices.steps.1": "Definir critérios para avaliar as APIs dos fornecedores, incluindo fiabilidade, segurança e conformidade.", "resource.vendor-management-best-practices.tips": "Personalize as Melhores Práticas de Gestão de Fornecedores ao seu domínio", "resource.vendor-management-best-practices.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.api-audit-checklist.title": "Lista de verificação de auditoria da API", "resource.api-audit-checklist.description": "Uma lista de verificação baseada no ciclo de vida para verificar a prontidão da API em design, entrega, publicação e conformidade utilizando critérios de auditoria e evidências definidos.", "resource.api-audit-checklist.outcomes": "Melhor compreensão dos princípios da lista de controlo de auditoria da API", "resource.api-audit-checklist.outcomes.1": "Abordagem normalizada utilizando a lista de verificação de auditoria da API", "resource.api-audit-checklist.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.api-audit-checklist.steps": "Utilize a lista de verificação de auditoria da API para garantir que a conceção da API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "resource.api-audit-checklist.steps.1": "Realize auditorias para avaliar a cobertura do ciclo de vida e verificar se a API satisfaz os padrões de negócio, conceção e operacionais.", "resource.api-audit-checklist.steps.2": "Certifique-se de que a documentação, os modelos de segurança, a configuração do gateway e os requisitos legais estejam claramente definidos, validados e comprovados por evidências.", "resource.api-audit-checklist.tips": "Cada item de auditoria associa o trabalho do ciclo de vida (etapas), as diretrizes regulatórias e as evidências de apoio para fornecer uma visão clara da prontidão da API.", "resource.api-audit-checklist.tips.1": "Utilize a Lista de Verificação de Auditoria de API de forma colaborativa entre as funções de negócios e tecnologia", "resource.api-business-model-canvas.title": "Canvas do Modelo de Negócio da API", "resource.api-business-model-canvas.description": "Avaliar estrategicamente a viabilidade do negócio de API, mapeando propostas de valor, segmentos de utilizadores e recursos-chave.", "resource.api-business-model-canvas.outcomes": "Estratégia comercial clara para APIs", "resource.api-business-model-canvas.outcomes.1": "Identificação dos principais recursos e parceiros", "resource.api-business-model-canvas.outcomes.2": "Alinhamento das características da API com os objetivos de negócio", "resource.api-business-model-canvas.steps": "Resumir a proposta de valor da API", "resource.api-business-model-canvas.steps.1": "Definir segmentos de utilizadores", "resource.api-business-model-canvas.steps.2": "Identificar estratégias de relações com os promotores", "resource.api-business-model-canvas.steps.3": "Mapear os canais de distribuição", "resource.api-business-model-canvas.steps.4": "documentar os principais recursos e actividades", "resource.api-business-model-canvas.steps.5": "Identificar os principais parceiros e partes interessadas", "resource.api-business-model-canvas.steps.6": "Destacar os benefícios e os custos", "resource.api-business-model-canvas.tips": "Começar com uma única API para garantir a clareza", "resource.api-business-model-canvas.tips.1": "Utilizar métricas como custo vs. benefício para dar prioridade às oportunidades", "resource.api-business-model-canvas.tips.2": "Validar os resultados com as principais partes interessadas", "resource.api-design-principles.title": "Princípios de conceção da API", "resource.api-design-principles.description": "Um guia conciso sobre usabilidade, descobribilidade e consistência da API, baseado em regras de design partilhadas e nas necessidades reais dos utilizadores.", "resource.api-design-principles.outcomes": "Melhor compreensão dos princípios de conceção das API", "resource.api-design-principles.outcomes.1": "Abordagem normalizada utilizando os princípios de conceção da API", "resource.api-design-principles.outcomes.2": "Melhoria da implementação das práticas de API relacionadas", "resource.api-design-principles.steps": "**Conceção que coloca o utilizador em primeiro lugar:** iniciar cada ciclo de APIOps recolhendo os objetivos do utilizador e os termos do domínio para que as APIs resolvam problemas reais.", "resource.api-design-principles.steps.1": "**Nomeação e comportamento consistentes:** aplicar convenções partilhadas para recursos, erros e formatos para tornar as APIs previsíveis.", "resource.api-design-principles.steps.2": "**Orientado para contratos:** capturar a interface com OpenAPI ou AsyncAPI antes da codificação para alinhar as equipas e permitir a automatização.", "resource.api-design-principles.steps.3": "**Usabilidade e facilidade de descoberta:** fornecer documentação e exemplos claros para que os programadores compreendam rapidamente como utilizar a API.", "resource.api-design-principles.steps.4": "**Iterar com segurança:** desenvolver os projetos em pequenos incrementos, com versões, para que as alterações não perturbem os utilizadores existentes.", "resource.api-design-principles.tips": "Personalizar os princípios de conceção de API ao seu domínio", "resource.api-design-principles.tips.1": "Utilize-o de forma colaborativa entre as funções de negócio e tecnológicas", "resource.api-value-proposition-canvas.title": "Canvas da Proposta de Valor da API", "resource.api-value-proposition-canvas.description": "Alinhar as funcionalidades da API com as necessidades dos utilizadores, mapeando tarefas, problemas e ganhos para os produtos da API.", "resource.api-value-proposition-canvas.outcomes": "Desenvolvimento de funcionalidades específicas", "resource.api-value-proposition-canvas.outcomes.1": "Alinhamento com as necessidades dos utilizadores", "resource.api-value-proposition-canvas.outcomes.2": "Melhoria da satisfação do utilizador da API", "resource.api-value-proposition-canvas.steps": "Listar as tarefas do percurso do utilizador", "resource.api-value-proposition-canvas.steps.1": "Identificar as características que proporcionam os ganhos esperados", "resource.api-value-proposition-canvas.steps.2": "Definir características para enfrentar os desafios", "resource.api-value-proposition-canvas.steps.3": "Mapear características para produtos API", "resource.api-value-proposition-canvas.tips": "Utilizar os dados do Canvas do Percurso do Cliente", "resource.api-value-proposition-canvas.tips.1": "Destaque para as características que aliviam as dores ou aumentam os ganhos", "resource.api-value-proposition-canvas.tips.2": "Validar as características com os utilizadores da API para garantir o alinhamento", "resource.business-impact-canvas.title": "Canvas de Impacto no Negócio", "resource.business-impact-canvas.description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "resource.business-impact-canvas.outcomes": "Infraestrutura API escalável", "resource.business-impact-canvas.outcomes.1": "Segurança e conformidade melhoradas", "resource.business-impact-canvas.outcomes.2": "Desempenho melhorado da API", "resource.business-impact-canvas.steps": "Riscos de disponibilidade: Identificar riscos e impactos.", "resource.business-impact-canvas.steps.1": "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "resource.business-impact-canvas.steps.2": "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "resource.business-impact-canvas.steps.3": "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "resource.business-impact-canvas.steps.4": "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "resource.business-impact-canvas.steps.5": "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados.", "resource.business-impact-canvas.tips": "Envolver os arquitectos e os promotores no processo de conceção", "resource.business-impact-canvas.tips.1": "Utilizar incidentes anteriores para identificar potenciais riscos", "resource.business-impact-canvas.tips.2": "Dar prioridade às APIs críticas com o maior impacto comercial", "resource.capacity-canvas.title": "Canvas de Capacidade", "resource.capacity-canvas.description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "resource.capacity-canvas.outcomes": "Alinhamento da capacidade da API com os volumes de negócios", "resource.capacity-canvas.outcomes.1": "Preparado para as futuras tendências de consumo", "resource.capacity-canvas.outcomes.2": "Estratégias definidas de armazenamento em cache e limitação de taxa", "resource.capacity-canvas.steps": "Documentar os volumes de negócios actuais", "resource.capacity-canvas.steps.1": "Prever as tendências de consumo futuras", "resource.capacity-canvas.steps.2": "Planear os picos de carga e os requisitos de disponibilidade", "resource.capacity-canvas.steps.3": "Definir estratégias de armazenamento em cache e de limitação de taxa", "resource.capacity-canvas.steps.4": "Propor estratégias de escalonamento", "resource.capacity-canvas.tips": "Utilizar a análise para prever tendências de crescimento", "resource.capacity-canvas.tips.1": "Definir cenários de picos de utilização", "resource.capacity-canvas.tips.2": "Incluir testes de escalabilidade na fase de planeamento", "resource.customer-journey-canvas.title": "Canvas do Percurso do Cliente", "resource.customer-journey-canvas.description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "resource.customer-journey-canvas.outcomes": "Melhoria da compreensão do cliente", "resource.customer-journey-canvas.outcomes.1": "Conceção melhorada da API", "resource.customer-journey-canvas.outcomes.2": "Melhor experiência do utilizador", "resource.customer-journey-canvas.steps": "Definir a personalidade do cliente", "resource.customer-journey-canvas.steps.1": "Identificar os factores que desencadeiam a viagem", "resource.customer-journey-canvas.steps.2": "Descrever o fim da viagem", "resource.customer-journey-canvas.steps.3": "Mapear as etapas do percurso com entradas/saídas", "resource.customer-journey-canvas.steps.4": "Identificar os problemas dos clientes", "resource.customer-journey-canvas.steps.5": "Resumir os ganhos dos clientes", "resource.customer-journey-canvas.steps.6": "Definir os inputs necessários e os outputs resultantes", "resource.customer-journey-canvas.steps.7": "Definir interações API para cada etapa", "resource.customer-journey-canvas.tips": "Iterar com o contributo da equipa para aperfeiçoar as etapas", "resource.customer-journey-canvas.tips.1": "Utilize os resultados deste quadro para informar outros quadros, como o quadro de proposta de valor da API", "resource.event-canvas.title": "Canvas de Eventos", "resource.event-canvas.description": "Conceber APIs orientadas para eventos, definindo eventos, accionadores e lógica de processamento.", "resource.event-canvas.outcomes": "Arquitetura orientada para eventos definida", "resource.event-canvas.outcomes.1": "Limpar os accionadores de eventos e a lógica de processamento", "resource.event-canvas.outcomes.2": "Melhoria da capacidade de resposta a alterações em tempo real", "resource.event-canvas.steps": "Identificar os principais eventos do sistema", "resource.event-canvas.steps.1": "Definir accionadores para cada evento", "resource.event-canvas.steps.2": "Descrever a lógica de processamento back-end para eventos", "resource.event-canvas.steps.3": "Especificar os resultados ou reconhecimentos resultantes", "resource.event-canvas.tips": "Utilizar esquemas de eventos para normalizar os formatos de eventos", "resource.event-canvas.tips.1": "documentar fluxos e dependências de eventos", "resource.event-canvas.tips.2": "Validar o processamento de eventos com casos de teste", "resource.graphql-canvas.title": "Canvas GraphQL", "resource.graphql-canvas.description": "Conceber APIs GraphQL definindo tipos, consultas, mutações e subscrições.", "resource.graphql-canvas.outcomes": "Conceção da API GraphQL estruturada", "resource.graphql-canvas.outcomes.1": "Tipos definidos e suas relações", "resource.graphql-canvas.outcomes.2": "Limpar consultas, mutações e subscrições", "resource.graphql-canvas.steps": "Que problemas estão os utilizadores de API a tentar resolver? De que dados necessitam?", "resource.graphql-canvas.steps.1": "Definir tipos GraphQL e seus atributos: Quais são os principais tipos expostos (por exemplo, utilizador, encomenda, produto)?", "resource.graphql-canvas.steps.2": "Mapear relações entre tipos: Como é que os tipos se relacionam uns com os outros em consultas aninhadas?", "resource.graphql-canvas.steps.3": "Especificar consultas para a recuperação de dados", "resource.graphql-canvas.steps.4": "Definir mutações para a modificação de dados: Que operações irão modificar os dados (por exemplo, criar, atualizar, eliminar)?", "resource.graphql-canvas.steps.5": "Assinaturas de esboços para actualizações em tempo real", "resource.graphql-canvas.steps.6": "Definir autenticação e autorização: Quem pode aceder a que campos ou tipos?", "resource.graphql-canvas.steps.7": "Considerar se existem restrições de paginação, filtragem ou limitação de taxa", "resource.graphql-canvas.tips": "Utilizar a introspeção para validar definições de tipos", "resource.graphql-canvas.tips.1": "documentar exemplos de consultas e mutações", "resource.graphql-canvas.tips.2": "Assegurar que os nomes dos tipos são descritivos e coerentes", "resource.interaction-canvas.title": "Canvas de Interação", "resource.interaction-canvas.description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "resource.interaction-canvas.outcomes": "Fluxos de trabalho de interação API claros", "resource.interaction-canvas.outcomes.1": "Entradas e saídas definidas para cada interação", "resource.interaction-canvas.outcomes.2": "Regras de validação consistentes em todas as interações", "resource.interaction-canvas.steps": "Mapear as interações da API para as tarefas do utilizador", "resource.interaction-canvas.steps.1": "Definir pontos finais para cada interação", "resource.interaction-canvas.steps.2": "documentar os inputs e outputs de cada interação", "resource.interaction-canvas.steps.3": "Especificar regras de validação e restrições", "resource.interaction-canvas.steps.4": "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento", "resource.interaction-canvas.tips": "Comece com casos de utilização comuns antes de lidar com casos extremos", "resource.interaction-canvas.tips.1": "Simular interações com dados simulados para validar fluxos de trabalho", "resource.interaction-canvas.tips.2": "documentar as respostas esperadas para interações bem e mal sucedidas", "resource.location-canvas.title": "Canvas de Localização", "resource.location-canvas.description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "resource.location-canvas.outcomes": "Conformidade com a regulamentação local", "resource.location-canvas.outcomes.1": "Desempenho optimizado da API em todas as regiões", "resource.location-canvas.outcomes.2": "Melhoria da compreensão das necessidades regionais", "resource.location-canvas.steps": "Mapa de localização dos fornecedores de API.", "resource.location-canvas.steps.1": "Documentar a localização dos utilizadores.", "resource.location-canvas.steps.2": "Identificar os regulamentos aplicáveis.", "resource.location-canvas.steps.3": "Documentar onde os dados devem residir.", "resource.location-canvas.steps.4": "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "resource.location-canvas.steps.5": "Validar o desempenho da rede em todas as regiões.", "resource.location-canvas.tips": "Colaborar com as equipas jurídicas e de conformidade", "resource.location-canvas.tips.1": "Validar o desempenho da rede nas principais regiões", "resource.location-canvas.tips.2": "Resolver proactivamente as restrições baseadas na localização", "resource.rest-canvas.title": "Canvas REST", "resource.rest-canvas.description": "Conceber APIs utilizando os princípios RESTful, definindo recursos, verbos e exemplos de pedidos e respostas.", "resource.rest-canvas.outcomes": "Conceção consistente da API RESTful", "resource.rest-canvas.outcomes.1": "Recursos definidos e suas interações", "resource.rest-canvas.outcomes.2": "Exemplos de pedidos e respostas para maior clareza", "resource.rest-canvas.steps": "Identificar os principais recursos expostos pela API", "resource.rest-canvas.steps.1": "Definir a estrutura do modelo de recursos da API", "resource.rest-canvas.steps.2": "Especificar os verbos HTTP utilizados para interagir com os recursos", "resource.rest-canvas.steps.3": "Fornecer exemplos de pedidos e respostas para cada verbo", "resource.rest-canvas.tips": "Utilizar métodos HTTP padrão (GET, POST, PUT, DELETE)", "resource.rest-canvas.tips.1": "Assegurar que os URIs dos recursos são intuitivos e coerentes", "resource.rest-canvas.tips.2": "tratamento de erros de documentos e códigos de resposta", "resource.capability-value-proposition-canvas.title": "Canvas da Proposta de Valor da Capacidade", "resource.capability-value-proposition-canvas.description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "resource.capability-value-proposition-canvas.outcomes": "Proposta de valor clara para a capacidade reutilizável", "resource.capability-value-proposition-canvas.outcomes.1": "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "resource.capability-value-proposition-canvas.outcomes.2": "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura", "resource.capability-value-proposition-canvas.steps": "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "resource.capability-value-proposition-canvas.steps.1": "Identifique funcionalidades da capacidade que permitem ganhos.", "resource.capability-value-proposition-canvas.steps.2": "Identifique funcionalidades da capacidade que aliviam dores.", "resource.capability-value-proposition-canvas.steps.3": "Agrupe as funcionalidades em capacidades reutilizáveis candidatas.", "resource.capability-value-proposition-canvas.tips": "Mantenha-se independente da tecnologia até os requisitos apontarem para um estilo.", "resource.capability-value-proposition-canvas.tips.1": "Utilize este recurso em vez do Canvas da Proposta de Valor da API quando a API ainda não é o estilo de implementação escolhido.", "resource.capability-business-model-canvas.title": "Canvas do Modelo de Negócio da Capacidade", "resource.capability-business-model-canvas.description": "Um canvas de modelo de negócio para capacidades de integração reutilizáveis, cobrindo valor, utilizadores, propriedade, envolvimento, custos e benefícios sem assumir disponibilização por API.", "resource.capability-business-model-canvas.outcomes": "Modelo operacional viável para a capacidade reutilizável", "resource.capability-business-model-canvas.outcomes.1": "Propriedade, utilizadores, canais, parceiros e necessidades de suporte clarificados", "resource.capability-business-model-canvas.outcomes.2": "Custos e benefícios visíveis antes do compromisso com a arquitetura", "resource.capability-business-model-canvas.steps": "Resuma a proposta de valor da capacidade.", "resource.capability-business-model-canvas.steps.1": "Identifique segmentos de utilizadores e canais de envolvimento.", "resource.capability-business-model-canvas.steps.2": "Defina atividades, recursos e parceiros-chave.", "resource.capability-business-model-canvas.steps.3": "Capte custos e benefícios.", "resource.capability-business-model-canvas.steps.4": "Clarifique propriedade, financiamento, suporte e expectativas de ciclo de vida.", "resource.capability-business-model-canvas.steps.5": "Valide o modelo com utilizadores, produtores e partes interessadas de governação.", "resource.capability-business-model-canvas.tips": "Utilize este recurso em vez do Canvas do Modelo de Negócio da API quando o estilo de implementação ainda está em aberto.", "resource.capability-business-model-canvas.tips.1": "Mantenha o foco na viabilidade da capacidade reutilizável, não numa ligação pontual.", "resource.consumer-experience-requirements-canvas.title": "Canvas de Requisitos da Experiência do Utilizador", "resource.consumer-experience-requirements-canvas.description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "resource.consumer-experience-requirements-canvas.outcomes": "Requisitos dos utilizadores independentes da tecnologia", "resource.consumer-experience-requirements-canvas.outcomes.1": "Necessidades de experiência e não funcionais captadas antes do início da conceção", "resource.consumer-experience-requirements-canvas.outcomes.2": "Implicações de arquitetura documentadas para a seleção do estilo", "resource.consumer-experience-requirements-canvas.steps": "Capte objetivos dos utilizadores e contexto de utilização.", "resource.consumer-experience-requirements-canvas.steps.1": "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "resource.consumer-experience-requirements-canvas.steps.2": "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "resource.consumer-experience-requirements-canvas.steps.3": "Resuma o que os requisitos implicam para possíveis estilos de arquitetura.", "resource.consumer-experience-requirements-canvas.tips": "Utilize isto como ponte entre o valor da capacidade e a decisão de arquitetura.", "resource.consumer-experience-requirements-canvas.tips.1": "Não escolha API, evento, ficheiro, stream ou produto de dados até os requisitos indicarem o melhor ajuste.", "resource.integration-style-selection-guide.title": "Guia de seleção do estilo de implementação", "resource.integration-style-selection-guide.description": "Orientação para escolher entre API, evento, ficheiro, stream, produto de dados, integração direta ou estilos de implementação híbridos com base nos requisitos e restrições.", "resource.integration-style-selection-guide.outcomes": "Estilo de implementação de integração justificado", "resource.integration-style-selection-guide.outcomes.1": "Compromissos documentados entre opções de estilo de implementação", "resource.integration-style-selection-guide.outcomes.2": "Estilo selecionado rastreável aos requisitos dos utilizadores, da plataforma, dos dados e da operação", "resource.integration-style-selection-guide.steps": "Compare estilos de implementação viáveis face a necessidades de latência, volume, acoplamento, propriedade dos dados, atualidade, governação e operabilidade.", "resource.integration-style-selection-guide.steps.1": "Identifique quando API, evento, ficheiro, stream, produto de dados, integração direta ou abordagens híbridas se ajustam ao caso de utilização.", "resource.integration-style-selection-guide.steps.2": "Documente restrições, riscos e dependências da plataforma para o estilo de implementação selecionado.", "resource.integration-style-selection-guide.steps.3": "Registe por que motivo as alternativas rejeitadas não foram selecionadas.", "resource.integration-style-selection-guide.tips": "Utilize depois de os requisitos estarem explícitos e antes de iniciar o desenho detalhado do contrato.", "resource.integration-style-selection-guide.tips.1": "Mantenha os recursos de REST, evento, GraphQL, ficheiro, stream e produto de dados como recursos opcionais de desenho subsequentes.", "resource.process-workflow-design-guide.title": "Guia de desenho do processo e workflow", "resource.process-workflow-design-guide.description": "Orientação para modelar passos do processo, papéis, passagens de responsabilidade, pontos de decisão, estados, entradas, saídas e exceções que moldam um workflow de automatização.", "resource.process-workflow-design-guide.outcomes": "Desenho claro do workflow de automatização", "resource.process-workflow-design-guide.outcomes.1": "Passos do processo e passagens de responsabilidade documentados antes da implementação", "resource.process-workflow-design-guide.outcomes.2": "Estados do workflow, entradas, saídas e caminhos de exceção compreendidos", "resource.process-workflow-design-guide.steps": "Mapeie o fluxo do processo atual e alvo, incluindo responsabilidades humanas e dos sistemas.", "resource.process-workflow-design-guide.steps.1": "Identifique gatilhos do workflow, estados, decisões, entradas de dados, saídas e critérios de conclusão.", "resource.process-workflow-design-guide.steps.2": "Documente passagens de responsabilidade entre utilizadores, sistemas, operações e papéis de suporte.", "resource.process-workflow-design-guide.steps.3": "Confirme que passos devem ser automatizados e quais exigem julgamento humano.", "resource.process-workflow-design-guide.tips": "Mantenha o desenho do processo separado do desenho de contratos de API ou de integração até o workflow estar claro.", "resource.process-workflow-design-guide.tips.1": "Utilize este como o recurso principal de desenho para workflows de automatização.", "resource.decision-business-rules-guide.title": "Guia de decisões e regras de negócio", "resource.decision-business-rules-guide.description": "Orientação para captar regras, limiares, decisões, aprovações, verificações de elegibilidade e responsabilidade pelas regras no desenho de automatizações.", "resource.decision-business-rules-guide.outcomes": "Decisões e regras de negócio explícitas", "resource.decision-business-rules-guide.outcomes.1": "Regras e limiares documentados com responsáveis", "resource.decision-business-rules-guide.outcomes.2": "Decisões da automatização rastreáveis a políticas, processos ou intenção de negócio", "resource.decision-business-rules-guide.steps": "Liste as decisões que a automatização deve tomar ou apoiar.", "resource.decision-business-rules-guide.steps.1": "Documente condições das regras, limiares, exceções, aprovações e pontos de escalamento.", "resource.decision-business-rules-guide.steps.2": "Identifique responsáveis pelas regras e governação de alterações para cada área de decisão.", "resource.decision-business-rules-guide.tips": "Separe regras de negócio estáveis de parâmetros operacionais configuráveis.", "resource.decision-business-rules-guide.tips.1": "Utilize exemplos e casos-limite para validar a interpretação das regras.", "resource.automation-trigger-handoff-exception-guide.title": "Guia de gatilhos, passagens de responsabilidade e exceções da automatização", "resource.automation-trigger-handoff-exception-guide.description": "Orientação para definir gatilhos de automatização, passagens para intervenção humana, tratamento de exceções, tentativas repetidas, ações compensatórias e caminhos de escalamento de suporte.", "resource.automation-trigger-handoff-exception-guide.outcomes": "Gatilhos de automatização e caminhos de exceção definidos", "resource.automation-trigger-handoff-exception-guide.outcomes.1": "Passagens para intervenção humana e escalamentos de suporte estão explícitos", "resource.automation-trigger-handoff-exception-guide.outcomes.2": "Exceções, tentativas repetidas e ações compensatórias desenhadas antes da entrega", "resource.automation-trigger-handoff-exception-guide.steps": "Defina os eventos, calendários, ações de utilizadores ou estados de sistema que acionam a automatização.", "resource.automation-trigger-handoff-exception-guide.steps.1": "Mapeie passagens da automatização para utilizadores, operadores ou equipas de suporte.", "resource.automation-trigger-handoff-exception-guide.steps.2": "Documente exceções, regras de nova tentativa, comportamento de timeout e caminhos alternativos.", "resource.automation-trigger-handoff-exception-guide.steps.3": "Defina alertas e limiares de escalamento para resultados de automatização falhados ou ambíguos.", "resource.automation-trigger-handoff-exception-guide.tips": "Desenhe caminhos de exceção como comportamento essencial do workflow, não como reflexão tardia.", "resource.automation-trigger-handoff-exception-guide.tips.1": "Inclua papéis de negócio e operações ao validar passagens de responsabilidade.", "resource.automation-testing-guide.title": "Guia de testes de automatização", "resource.automation-testing-guide.description": "Orientação para testar workflows automatizados, decisões, integrações, exceções, comportamento de rollback, supervisão e impacto nos utilizadores antes da publicação.", "resource.automation-testing-guide.outcomes": "Comportamento da automatização validado", "resource.automation-testing-guide.outcomes.1": "Testes de workflow, regras, exceções e integração definidos", "resource.automation-testing-guide.outcomes.2": "Confiança na publicação para caminhos automatizados e assistidos por pessoas", "resource.automation-testing-guide.steps": "Crie testes para caminhos esperados, casos-limite, exceções, tentativas repetidas e passagens de responsabilidade.", "resource.automation-testing-guide.steps.1": "Valide regras de negócio e resultados de decisão com dados representativos.", "resource.automation-testing-guide.steps.2": "Teste rollback, recuperação, observabilidade e caminhos de intervenção manual.", "resource.automation-testing-guide.steps.3": "Inclua utilizadores e operadores em testes de aceitação quando a automatização altera práticas de trabalho.", "resource.automation-testing-guide.tips": "Utilize cenários e formatos de dados semelhantes aos de produção sem expor dados sensíveis.", "resource.automation-testing-guide.tips.1": "Mantenha as evidências de teste disponíveis para a revisão de prontidão.", "resource.automation-operational-ownership-guide.title": "Guia de responsabilidade operacional da automatização", "resource.automation-operational-ownership-guide.description": "Orientação para definir responsabilidade, runbooks, supervisão, suporte, monitorização, controlo de alterações e responsabilidades de melhoria contínua para automatizações.", "resource.automation-operational-ownership-guide.outcomes": "Modelo operacional claro para a automatização", "resource.automation-operational-ownership-guide.outcomes.1": "Responsabilidades de propriedade, suporte e escalamento atribuídas", "resource.automation-operational-ownership-guide.outcomes.2": "Práticas de monitorização e alteração prontas para operação em produção", "resource.automation-operational-ownership-guide.steps": "Defina responsáveis de negócio, técnicos e operacionais pela automatização.", "resource.automation-operational-ownership-guide.steps.1": "Documente runbooks, caminhos de suporte, sinais de monitorização, expectativas de serviço e regras de escalamento.", "resource.automation-operational-ownership-guide.steps.2": "Defina controlo de alterações e práticas de revisão para atualizações de workflow, plataforma e regras.", "resource.automation-operational-ownership-guide.tips": "Não publique uma automatização sem um responsável nomeado por exceções e melhoria contínua.", "resource.automation-operational-ownership-guide.tips.1": "Torne visíveis as necessidades de supervisão antes de terminar o planeamento da entrega.", "resource.automation-rollback-supervision-guide.title": "Guia de rollback e supervisão da automatização", "resource.automation-rollback-supervision-guide.description": "Orientação para desenhar caminhos de rollback, pausa, substituição manual, monitorização, supervisão e recuperação para automatizações.", "resource.automation-rollback-supervision-guide.outcomes": "Caminhos controlados de recuperação da automatização", "resource.automation-rollback-supervision-guide.outcomes.1": "Comportamento de rollback, pausa e substituição manual documentado", "resource.automation-rollback-supervision-guide.outcomes.2": "Necessidades de supervisão e responsabilidades de recuperação definidas", "resource.automation-rollback-supervision-guide.steps": "Identifique ações que devem poder ser revertidas, pausadas ou substituídas manualmente.", "resource.automation-rollback-supervision-guide.steps.1": "Defina procedimentos de rollback, compensação e recuperação para resultados de automatização falhados ou incorretos.", "resource.automation-rollback-supervision-guide.steps.2": "Documente limiares de supervisão, alertas e pontos de decisão manual.", "resource.automation-rollback-supervision-guide.steps.3": "Valide os procedimentos de recuperação antes da publicação.", "resource.automation-rollback-supervision-guide.tips": "Trate rollback e supervisão como parte do desenho do workflow e do plano de entrega.", "resource.automation-rollback-supervision-guide.tips.1": "Utilize incidentes operacionais e quase incidentes para refinar critérios de supervisão.", "resource.automation-readiness-checklist.title": "Checklist de prontidão da automatização", "resource.automation-readiness-checklist.description": "Uma checklist para validar workflow de automatização, controlos, risco, conformidade, supervisão humana, evidências de teste, rollback, operações e prontidão para publicação.", "resource.automation-readiness-checklist.outcomes": "Prontidão da automatização documentada", "resource.automation-readiness-checklist.outcomes.1": "Lacunas de prontidão conhecidas e mitigações antes da publicação", "resource.automation-readiness-checklist.outcomes.2": "Evidências para qualidade, risco, conformidade, supervisão e aprovação operacional", "resource.automation-readiness-checklist.steps": "Reveja desenho do workflow, regras de negócio, controlos, acesso, tratamento de dados e caminhos de exceção.", "resource.automation-readiness-checklist.steps.1": "Verifique evidências de teste, procedimentos de rollback, modelo de supervisão e prontidão do suporte.", "resource.automation-readiness-checklist.steps.2": "Confirme responsabilidade, runbooks, monitorização, controlos de alteração e aprovação de publicação.", "resource.automation-readiness-checklist.steps.3": "Registe lacunas por resolver, decisões e riscos aceites antes da publicação.", "resource.automation-readiness-checklist.tips": "Utilize antes da publicação e novamente após alterações materiais ao workflow ou às regras.", "resource.automation-readiness-checklist.tips.1": "Torne explícitas nas evidências a supervisão humana e a gestão de exceções.", "resource.automation-rollout-enablement-guide.title": "Guia de rollout e enablement da automatização", "resource.automation-rollout-enablement-guide.description": "Orientação para implementar automatizações com comunicação aos utilizadores, onboarding, instruções operacionais, caminhos de suporte, gestão da mudança e ciclos de feedback.", "resource.automation-rollout-enablement-guide.outcomes": "Utilizadores e operadores da automatização preparados", "resource.automation-rollout-enablement-guide.outcomes.1": "Comunicação de rollout, onboarding e caminhos de suporte preparados", "resource.automation-rollout-enablement-guide.outcomes.2": "Utilizadores e operadores compreendem como o trabalho muda após a publicação da automatização", "resource.automation-rollout-enablement-guide.steps": "Defina públicos do rollout, calendário, canais de comunicação e necessidades de formação.", "resource.automation-rollout-enablement-guide.steps.1": "Publique instruções operacionais, caminhos de suporte, orientação para exceções e contactos de escalamento.", "resource.automation-rollout-enablement-guide.steps.2": "Planeie suporte de transição para utilizadores, operadores e responsáveis pelo processo.", "resource.automation-rollout-enablement-guide.steps.3": "Recolha feedback após o rollout e alimente o backlog com melhorias.", "resource.automation-rollout-enablement-guide.tips": "Utilize linguagem de rollout para automatizações em vez de tratar enablement como publicação de API.", "resource.automation-rollout-enablement-guide.tips.1": "Inclua tanto os utilizadores afetados pelo processo como os operadores responsáveis pela automatização.", "resource.api-community-engagement-strategies.tips.2": "Utilize este recurso quando uma API for o estilo de implementação selecionado.", "resource.api-development-best-practices.tips.2": "Utilize este recurso quando uma API for o estilo de implementação selecionado.", "resource.api-metrics-and-analytics.tips.2": "Utilize este recurso quando uma API for o estilo de implementação selecionado.", "resource.api-testing-best-practices.tips.2": "Utilize este recurso quando uma API for o estilo de implementação selecionado.", "resource.apiops-CI-CD-for-apis.tips.2": "Utilize este recurso quando uma API for o estilo de implementação selecionado.", "resource.api-audit-checklist.tips.2": "Utilize este recurso quando uma API for o estilo de implementação selecionado.", "exit_criteria": "Critérios de saída", "entry_criteria": "Critérios de entrada", "criterion.metrics-feedback-available": "Sinais de mercado relevantes, feedback ou conhecimento operacional estão disponíveis para orientar esta oportunidade de capacidade.", "criterion.business-goals-defined": "Os objetivos de negócio estão definidos.", "criterion.market-research-done": "A investigação de mercado identifica oportunidades de capacidade.", "criterion.stakeholder-approval": "As partes interessadas relevantes concordam que vale a pena explorar e priorizar esta oportunidade de capacidade.", "criterion.api-opportunity-documented": "A oportunidade de capacidade está identificada e documentada.", "criterion.api-reusability": "A capacidade responde a uma necessidade clara de negócio e é reutilizável pelos utilizadores previstos.", "criterion.hide-backend-discrepancies": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "criterion.value-prop-validated": "A proposta de valor da capacidade foi validada com partes interessadas de negócio e utilizadores.", "criterion.consumer-segments-identified": "Os segmentos de utilizadores estão identificados.", "criterion.api-roadmap-defined": "Está definido um roadmap de implementação de alto nível.", "criterion.architecture-patterns-validated": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "criterion.design-reflects-business-value": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "criterion.api-consistency": "O desenho da interface segue os standards e convenções de desenho acordados.", "criterion.api-contract-tested": "O contrato de interface foi validado e testado face aos requisitos funcionais e não funcionais.", "criterion.automation-workflow-validated": "O workflow, as regras, as integrações e os contratos de interface relevantes foram validados e testados.", "criterion.api-description-available": "A interface e as suas capacidades estão documentadas de forma suficientemente clara para revisão, auditoria e onboarding.", "criterion.audit-passed": "A solução passa as verificações de qualidade, segurança, conformidade e prontidão.", "criterion.audit-reports-shared": "As conclusões da auditoria e as decisões de correção são partilhadas com as partes interessadas relevantes.", "criterion.api-ready-for-publishing": "A capacidade está pronta para ser publicada ou disponibilizada através do mecanismo de entrega selecionado.", "criterion.api-documentation-ready": "A documentação orientada para os utilizadores e os materiais de onboarding estão prontos.", "criterion.consumer-support-ready": "Os processos de onboarding, suporte e comunicação para utilizadores estão prontos.", "criterion.legal-compliance-clear": "Os requisitos legais, de privacidade e de conformidade para publicação ou disponibilização estão definidos e compreendidos.", "stakeholder.involvement.lead": "Líder", "stakeholder.involvement.core": "Núcleo", "stakeholder.involvement.consulted": "Consultado", "stakeholder.business-owner.title": "Responsável de negócio", "stakeholder.business-owner.description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "stakeholder.api-program-owner.title": "Responsável pelo programa API", "stakeholder.api-program-owner.description": "Coordena as práticas do portefólio de APIs, o alinhamento organizacional e o desenvolvimento de capacidades API a longo prazo.", "stakeholder.api-product-owner.title": "Responsável pelo produto API", "stakeholder.api-product-owner.description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "stakeholder.capability-owner.title": "Responsável pela capacidade", "stakeholder.capability-owner.description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "stakeholder.domain-specialist.title": "Especialista de domínio", "stakeholder.domain-specialist.description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "stakeholder.customer-specialist.title": "Representante de cliente ou parceiro", "stakeholder.customer-specialist.description": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "stakeholder.api-consumer-specialist.title": "Representante dos utilizadores da API", "stakeholder.api-consumer-specialist.description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "stakeholder.platform-architect.title": "Arquiteto de plataforma", "stakeholder.platform-architect.description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "stakeholder.api-architect.title": "Arquiteto API", "stakeholder.api-architect.description": "Responsável pela arquitetura API, pelos princípios de desenho e pela qualidade dos contratos de interface.", "stakeholder.integration-architect.title": "Arquiteto de integração", "stakeholder.integration-architect.description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "stakeholder.platform-owner.title": "Responsável pela plataforma", "stakeholder.platform-owner.description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "stakeholder.api-designer.title": "Designer API", "stakeholder.api-designer.description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "stakeholder.api-engineer.title": "Engenheiro de entrega", "stakeholder.api-engineer.description": "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.", "stakeholder.automation-owner.title": "Responsável pela automatização", "stakeholder.automation-owner.description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "stakeholder.process-owner.title": "Responsável pelo processo", "stakeholder.process-owner.description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "stakeholder.automation-engineer.title": "Engenheiro de automatização", "stakeholder.automation-engineer.description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "stakeholder.security-specialist.title": "Especialista em segurança", "stakeholder.security-specialist.description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "stakeholder.compliance-specialist.title": "Especialista em conformidade e jurídico", "stakeholder.compliance-specialist.description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "stakeholder.governance-specialist.title": "Responsável pela governação API", "stakeholder.governance-specialist.description": "Representa práticas de revisão, auditoria e governação em toda a organização para qualidade e conformidade das APIs.", "stakeholder.api-devrel-specialist.title": "Responsável por documentação e DevRel", "stakeholder.api-devrel-specialist.description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "stakeholder.operations-specialist.title": "Responsável por suporte e operações", "stakeholder.operations-specialist.description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "stakeholder.partner-specialist.title": "Gestor de parceiros ou fornecedores", "stakeholder.partner-specialist.description": "Coordena relações com parceiros, fornecedores ou prestadores externos que influenciam a estratégia e entrega da capacidade ou API.", "lines.title": "Linhas", "lines.description": "Uma coleção de linhas de API que orientam o desenvolvimento e a gestão de APIs.", "line.business-opportunities-line.title": "Linha oportunidades de negócio", "line.business-opportunities-line.description": "Centra-se na identificação e aproveitamento de oportunidades de negócio através de APIs.", "line.platform-architecture-line.title": "Linha de arquitetura da plataforma", "line.platform-architecture-line.description": "Abrange os aspetos arquiteturais das plataformas API.", "line.api-design-line.title": "Linha de conceção de API", "line.api-design-line.description": "Centra-se nos princípios e práticas de conceção de APIs.", "line.delivery-line.title": "Linha de entrega", "line.delivery-line.description": "Abrange os processos e práticas de entrega de APIs.", "line.publishing-and-adoption-line.title": "Linha de publicação e adoção", "line.publishing-and-adoption-line.description": "Centra-se na publicação de APIs e na garantia da sua adoção pelos consumidores.", "line.operating-model-line.title": "Linha de modelo operacional", "line.operating-model-line.description": "Abrange o modelo operacional para gestão e governação de API." }, "cycles": [ { "id": "capability-productization-cycle", "slug": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação.", "purpose": "Identificar e transformar capacidades digitais reutilizaveis em produto antes de escolher um estilo de implementacao API, evento, ficheiro, stream, produto de dados, servico com IA, integracao direta ou hibrido.", "audiences": [], "audienceStakeholders": [ { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "lead", "responsibilities": [ { "resourceId": "capabilityValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da Capacidade", "canvasId": "capabilityValuePropositionCanvas", "role": "suggested-answer-owner" }, { "resourceId": "capabilityBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da Capacidade", "canvasId": "capabilityBusinessModelCanvas", "role": "suggested-answer-owner" } ] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [ { "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "role": "suggested-answer-owner" } ] }, { "id": "customer-specialist", "sourceKey": "customer-specialist", "sourceStakeholderId": "customer-specialist", "title": "Representante de cliente ou parceiro", "description": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "involvement": "core", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [ { "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "role": "suggested-answer-owner" } ] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [ { "resourceId": "consumerExperienceRequirementsCanvas", "resourceTitle": "Canvas de Requisitos da Experiência do Utilizador", "canvasId": "consumerExperienceRequirementsCanvas", "role": "suggested-answer-owner" } ] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "lead", "responsibilities": [ { "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "role": "suggested-answer-owner" } ] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "core", "responsibilities": [ { "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas", "role": "suggested-answer-owner" } ] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "lead", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "lead", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "governance-specialist", "sourceKey": "governance-specialist", "sourceStakeholderId": "governance-specialist", "title": "Responsável pela governação API", "description": "Representa práticas de revisão, auditoria e governação em toda a organização para qualidade e conformidade das APIs.", "involvement": "lead", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "core", "responsibilities": [] } ], "entryCriteria": [ "business-goals-defined", "stakeholder-approval" ], "exitCriteria": [ "value-prop-validated", "architecture-patterns-validated", "audit-passed" ], "entryCriteriaDetails": [ { "id": "business-goals-defined", "title": "Os objetivos de negócio estão definidos.", "description": "Business goals are defined." }, { "id": "stakeholder-approval", "title": "As partes interessadas relevantes concordam que vale a pena explorar e priorizar esta oportunidade de capacidade.", "description": "Relevant stakeholders agree this API opportunity is worth exploring and prioritizing." } ], "exitCriteriaDetails": [ { "id": "value-prop-validated", "title": "A proposta de valor da capacidade foi validada com partes interessadas de negócio e utilizadores.", "description": "The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders." }, { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "audit-passed", "title": "A solução passa as verificações de qualidade, segurança, conformidade e prontidão.", "description": "The API passes compliance, security, and audit checks." } ], "questionnaireResources": [ { "stationId": "api-product-strategy", "stationTitle": "Estrategia da capacidade", "resourceId": "capabilityValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da Capacidade", "canvasId": "capabilityValuePropositionCanvas", "suggestedAnswerOwner": { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "lead", "responsibilities": [ { "resourceId": "capabilityValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da Capacidade", "canvasId": "capabilityValuePropositionCanvas", "role": "suggested-answer-owner" }, { "resourceId": "capabilityBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da Capacidade", "canvasId": "capabilityBusinessModelCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-product-strategy", "stationTitle": "Estrategia da capacidade", "resourceId": "capabilityBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da Capacidade", "canvasId": "capabilityBusinessModelCanvas", "suggestedAnswerOwner": { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "lead", "responsibilities": [ { "resourceId": "capabilityValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da Capacidade", "canvasId": "capabilityValuePropositionCanvas", "role": "suggested-answer-owner" }, { "resourceId": "capabilityBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da Capacidade", "canvasId": "capabilityBusinessModelCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-product-strategy", "stationTitle": "Estrategia da capacidade", "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "suggestedAnswerOwner": { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [ { "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-product-strategy", "stationTitle": "Estrategia da capacidade", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "suggestedAnswerOwner": { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [ { "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-consumer-experience", "stationTitle": "Requisitos e onboarding de utilizadores", "resourceId": "consumerExperienceRequirementsCanvas", "resourceTitle": "Canvas de Requisitos da Experiência do Utilizador", "canvasId": "consumerExperienceRequirementsCanvas", "suggestedAnswerOwner": { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [ { "resourceId": "consumerExperienceRequirementsCanvas", "resourceTitle": "Canvas de Requisitos da Experiência do Utilizador", "canvasId": "consumerExperienceRequirementsCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-platform-architecture", "stationTitle": "Decisões de arquitetura e plataforma", "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "suggestedAnswerOwner": { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "lead", "responsibilities": [ { "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-platform-architecture", "stationTitle": "Decisões de arquitetura e plataforma", "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas", "suggestedAnswerOwner": { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "core", "responsibilities": [ { "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-platform-architecture", "stationTitle": "Decisões de arquitetura e plataforma", "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas", "suggestedAnswerOwner": { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "core", "responsibilities": [ { "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas", "role": "suggested-answer-owner" } ] } } ], "stations": [ { "index": 1, "id": "api-product-strategy", "slug": "method/api-product-strategy", "icon": "strategy-outline", "title": "Estrategia da capacidade", "description": "Antes de construir qualquer coisa, defina o valor, os consumidores, a propriedade e os objetivos de negócio da capacidade.", "whyItMatters": "O trabalho de integração e API salta muitas vezes demasiado cedo para um padrão técnico. Esta estação mantém a equipa focada na jornada de negócio, no significado do domínio, no valor, no potencial de reutilização, na propriedade e na viabilidade antes de selecionar APIs, eventos, ficheiros, streams, produtos de dados ou integração direta.", "applyInWork": "Utilize canvases partilhados de jornada, domínio, proposta de valor e modelo de negócio para recolher requisitos independentes da tecnologia e decidir se a capacidade deve ser reutilizável.", "outcomes": [ "Uma declaração de oportunidade de capacidade independente da tecnologia", "Compreensão partilhada dos consumidores, produtores, conceitos de domínio e potencial de reutilização", "Uma proposta de valor e um modelo de negócio da capacidade antes da seleção da arquitetura" ], "steps": [ { "text": "Mapeie a jornada do cliente ou parceiro que cria a necessidade da capacidade e revela tarefas, dores, ganhos, entradas, saídas e pontos de decisão.", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas" }, { "text": "Defina as entidades principais, atributos, relações, propriedade e regras de negócio que a capacidade deve respeitar.", "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas" }, { "text": "Utilize o Canvas da Proposta de Valor da Capacidade para captar tarefas, ganhos, dores e funcionalidades reutilizáveis da capacidade para os consumidores, sem nomear a tecnologia de disponibilização demasiado cedo.", "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas" }, { "text": "Utilize o Canvas do Modelo de Negócio da Capacidade para clarificar propriedade, parceiros, canais, custos, benefícios, suporte e expectativas de ciclo de vida da capacidade reutilizável.", "resourceId": "apiBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da API", "canvasId": "apiBusinessModelCanvas" } ], "questions": [ "Mapeie a jornada do cliente ou parceiro que cria a necessidade da capacidade e revela tarefas, dores, ganhos, entradas, saídas e pontos de decisão.", "Defina as entidades principais, atributos, relações, propriedade e regras de negócio que a capacidade deve respeitar.", "Utilize o Canvas da Proposta de Valor da Capacidade para captar tarefas, ganhos, dores e funcionalidades reutilizáveis da capacidade para os consumidores, sem nomear a tecnologia de disponibilização demasiado cedo.", "Utilize o Canvas do Modelo de Negócio da Capacidade para clarificar propriedade, parceiros, canais, custos, benefícios, suporte e expectativas de ciclo de vida da capacidade reutilizável.", "Utilize canvases partilhados de jornada, domínio, proposta de valor e modelo de negócio para recolher requisitos independentes da tecnologia e decidir se a capacidade deve ser reutilizável.", "O trabalho de integração e API salta muitas vezes demasiado cedo para um padrão técnico. Esta estação mantém a equipa focada na jornada de negócio, no significado do domínio, no valor, no potencial de reutilização, na propriedade e na viabilidade antes de selecionar APIs, eventos, ficheiros, streams, produtos de dados ou integração direta." ], "criteria": [ "metrics-feedback-available", "business-goals-defined", "market-research-done", "stakeholder-approval" ], "criteriaDetails": [ { "id": "metrics-feedback-available", "title": "Sinais de mercado relevantes, feedback ou conhecimento operacional estão disponíveis para orientar esta oportunidade de capacidade.", "description": "Relevant market signals, feedback, or operational insights are available to guide this API opportunity." }, { "id": "business-goals-defined", "title": "Os objetivos de negócio estão definidos.", "description": "Business goals are defined." }, { "id": "market-research-done", "title": "A investigação de mercado identifica oportunidades de capacidade.", "description": "Market research identifies API opportunities." }, { "id": "stakeholder-approval", "title": "As partes interessadas relevantes concordam que vale a pena explorar e priorizar esta oportunidade de capacidade.", "description": "Relevant stakeholders agree this API opportunity is worth exploring and prioritizing." } ], "baseTitle": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "strategy", "stakeholders": [ { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "lead", "responsibilities": [ { "resourceId": "capabilityValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da Capacidade", "canvasId": "capabilityValuePropositionCanvas", "role": "suggested-answer-owner" }, { "resourceId": "capabilityBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da Capacidade", "canvasId": "capabilityBusinessModelCanvas", "role": "suggested-answer-owner" } ] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [ { "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "role": "suggested-answer-owner" } ] }, { "id": "customer-specialist", "sourceKey": "customer-specialist", "sourceStakeholderId": "customer-specialist", "title": "Representante de cliente ou parceiro", "description": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "involvement": "core", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [ { "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "role": "suggested-answer-owner" } ] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-program-owner", "sourceKey": "api-program-owner", "sourceStakeholderId": "api-program-owner", "title": "Responsável pelo programa API", "description": "Coordena as práticas do portefólio de APIs, o alinhamento organizacional e o desenvolvimento de capacidades API a longo prazo.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityBusinessModelCanvas", "slug": "resources/capability-business-model-canvas", "title": "Canvas do Modelo de Negócio da Capacidade", "description": "Um canvas de modelo de negócio para capacidades de integração reutilizáveis, cobrindo valor, utilizadores, propriedade, envolvimento, custos e benefícios sem assumir disponibilização por API.", "category": "canvas", "icon": "dashboard-outline", "order": 3.1, "outcomes": [ "Modelo operacional viável para a capacidade reutilizável", "Propriedade, utilizadores, canais, parceiros e necessidades de suporte clarificados", "Custos e benefícios visíveis antes do compromisso com a arquitetura" ], "steps": [ "Resuma a proposta de valor da capacidade.", "Identifique segmentos de utilizadores e canais de envolvimento.", "Defina atividades, recursos e parceiros-chave.", "Capte custos e benefícios.", "Clarifique propriedade, financiamento, suporte e expectativas de ciclo de vida.", "Valide o modelo com utilizadores, produtores e partes interessadas de governação." ], "canvasId": "capabilityBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false } ], "evidence": [ "design-artifact", "documentation", "research", "roadmap" ] }, { "index": 2, "id": "api-consumer-experience", "slug": "method/api-consumer-experience", "icon": "deployed-code-account-outline", "title": "Requisitos e onboarding de utilizadores", "description": "Recolha requisitos de integração dos consumidores, normas, requisitos não funcionais, expectativas de serviço, restrições, necessidades de segurança, protocolos permitidos, atualidade dos dados, SLAs, observabilidade, recuperação, requisitos de adoção e responsabilidades dos produtores.", "whyItMatters": "A arquitetura certa depende dos objetivos dos consumidores, das expectativas de integração, dos níveis de serviço, das necessidades de qualidade dos dados, da tolerância à mudança, da observabilidade, do suporte e das restrições dos produtores.", "applyInWork": "Utilize orientação de experiência e integração de consumidores para tornar explícitas as expectativas de consumidores e produtores.", "outcomes": [ "Requisitos dos consumidores e expectativas de integração documentados", "Responsabilidades dos produtores e expectativas de suporte claras", "Restrições relevantes para a arquitetura prontas para apoiar decisões", "Adoção melhorada através de empatia com os consumidores, normas e clareza dos produtores" ], "steps": [ { "text": "Utilize o Canvas de Requisitos da Experiência do Consumidor para captar objetivos dos consumidores, disponibilidade, atualidade, volume, desempenho, qualidade dos dados, segurança, integração, mudança, observabilidade e expectativas de recuperação.", "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas" }, { "text": "Utilize orientação de integração para descrever como os consumidores vão encontrar, solicitar, testar, obter aprovação e começar a utilizar a capacidade.", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas" }, { "text": "Utilize a jornada e os requisitos resultantes para melhorar a integração, a documentação, o suporte e os ciclos de feedback dos consumidores da capacidade.", "resourceId": "api-onboarding-best-practices", "resourceTitle": "Boas práticas de integração de API", "canvasId": null } ], "questions": [ "Utilize o Canvas de Requisitos da Experiência do Consumidor para captar objetivos dos consumidores, disponibilidade, atualidade, volume, desempenho, qualidade dos dados, segurança, integração, mudança, observabilidade e expectativas de recuperação.", "Utilize orientação de integração para descrever como os consumidores vão encontrar, solicitar, testar, obter aprovação e começar a utilizar a capacidade.", "Utilize a jornada e os requisitos resultantes para melhorar a integração, a documentação, o suporte e os ciclos de feedback dos consumidores da capacidade.", "Utilize orientação de experiência e integração de consumidores para tornar explícitas as expectativas de consumidores e produtores.", "A arquitetura certa depende dos objetivos dos consumidores, das expectativas de integração, dos níveis de serviço, das necessidades de qualidade dos dados, da tolerância à mudança, da observabilidade, do suporte e das restrições dos produtores." ], "criteria": [ "api-opportunity-documented", "api-reusability", "hide-backend-discrepancies", "value-prop-validated", "consumer-segments-identified", "api-roadmap-defined" ], "criteriaDetails": [ { "id": "api-opportunity-documented", "title": "A oportunidade de capacidade está identificada e documentada.", "description": "Individual API opportunities are identified and documented." }, { "id": "api-reusability", "title": "A capacidade responde a uma necessidade clara de negócio e é reutilizável pelos utilizadores previstos.", "description": "The API meets a clear business need and is reusable for multiple API consumers." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "value-prop-validated", "title": "A proposta de valor da capacidade foi validada com partes interessadas de negócio e utilizadores.", "description": "The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders." }, { "id": "consumer-segments-identified", "title": "Os segmentos de utilizadores estão identificados.", "description": "API consumer segments (internal and external) are identified." }, { "id": "api-roadmap-defined", "title": "Está definido um roadmap de implementação de alto nível.", "description": "High-level roadmaps for API development are established." } ], "baseTitle": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "strategy", "stakeholders": [ { "id": "customer-specialist", "sourceKey": "customer-specialist", "sourceStakeholderId": "customer-specialist", "title": "Representante de cliente ou parceiro", "description": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "involvement": "lead", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [ { "resourceId": "consumerExperienceRequirementsCanvas", "resourceTitle": "Canvas de Requisitos da Experiência do Utilizador", "canvasId": "consumerExperienceRequirementsCanvas", "role": "suggested-answer-owner" } ] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "core", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "consulted", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "design-artifact", "documentation", "consumer-feedback" ] }, { "index": 3, "id": "api-platform-architecture", "slug": "method/api-platform-architecture", "icon": "code-blocks-outline", "title": "Decisões de arquitetura e plataforma", "description": "Utilize requisitos e restrições para decidir o padrão de arquitetura certo e as capacidades de plataforma de suporte.", "whyItMatters": "As escolhas de arquitetura devem resultar de evidências sobre impacto de negócio, localizações, fronteiras de confiança, capacidade, latência, propriedade dos dados, consistência, operabilidade, segurança, privacidade, governação e custo.", "applyInWork": "Compare estilos de arquitetura viáveis com os requisitos recolhidos e documente o padrão selecionado e a respetiva justificação.", "outcomes": [ "Uma escolha de arquitetura justificada", "Riscos, localizações, capacidade, segurança, privacidade e restrições de operabilidade documentados", "Justificação clara para API, evento, ficheiro, stream, produto de dados, integração direta ou disponibilização híbrida" ], "steps": [ { "text": "Utilize o Canvas de Impacto no Negócio para identificar riscos de disponibilidade, segurança e dados que influenciam as opções de arquitetura.", "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas" }, { "text": "Utilize o Canvas de Localizações para captar restrições geopolíticas, regulamentares, de rede, residência e fronteiras de confiança.", "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas" }, { "text": "Utilize o Canvas de Capacidade para captar volumes atuais e futuros, picos, latência, cache, limitação de pedidos e expectativas de escala.", "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas" }, { "text": "Utilize orientação de métricas e análise para definir como a capacidade escolhida será monitorizada e melhorada.", "resourceId": "api-metrics-and-analytics", "resourceTitle": "Métricas e análise de API", "canvasId": null } ], "questions": [ "Utilize o Canvas de Impacto no Negócio para identificar riscos de disponibilidade, segurança e dados que influenciam as opções de arquitetura.", "Utilize o Canvas de Localizações para captar restrições geopolíticas, regulamentares, de rede, residência e fronteiras de confiança.", "Utilize o Canvas de Capacidade para captar volumes atuais e futuros, picos, latência, cache, limitação de pedidos e expectativas de escala.", "Utilize orientação de métricas e análise para definir como a capacidade escolhida será monitorizada e melhorada.", "Compare estilos de arquitetura viáveis com os requisitos recolhidos e documente o padrão selecionado e a respetiva justificação.", "As escolhas de arquitetura devem resultar de evidências sobre impacto de negócio, localizações, fronteiras de confiança, capacidade, latência, propriedade dos dados, consistência, operabilidade, segurança, privacidade, governação e custo." ], "criteria": [ "api-reusability", "hide-backend-discrepancies", "value-prop-validated", "consumer-segments-identified", "api-roadmap-defined" ], "criteriaDetails": [ { "id": "api-reusability", "title": "A capacidade responde a uma necessidade clara de negócio e é reutilizável pelos utilizadores previstos.", "description": "The API meets a clear business need and is reusable for multiple API consumers." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "value-prop-validated", "title": "A proposta de valor da capacidade foi validada com partes interessadas de negócio e utilizadores.", "description": "The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders." }, { "id": "consumer-segments-identified", "title": "Os segmentos de utilizadores estão identificados.", "description": "API consumer segments (internal and external) are identified." }, { "id": "api-roadmap-defined", "title": "Está definido um roadmap de implementação de alto nível.", "description": "High-level roadmaps for API development are established." } ], "baseTitle": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "architecture", "stakeholders": [ { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "lead", "responsibilities": [ { "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "role": "suggested-answer-owner" } ] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "core", "responsibilities": [ { "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas", "role": "suggested-answer-owner" } ] }, { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "core", "responsibilities": [ { "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas", "role": "suggested-answer-owner" } ] }, { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false } ], "evidence": [ "architecture-decision", "documentation", "platform-config", "metrics" ] }, { "index": 4, "id": "api-design", "slug": "method/api-design", "icon": "api", "title": "Conceção da solução e da interface", "description": "Conceba o contrato de interface e o modelo de interação para o estilo de disponibilização selecionado.", "whyItMatters": "Depois de conhecido o padrão de arquitetura, a conceção deve transformar os requisitos da capacidade em contratos de interface, interações, esquemas, regras de dados, expectativas de ciclo de vida e obrigações dos consumidores claros.", "applyInWork": "Selecione os recursos de conceção adequados ao estilo de disponibilização escolhido e documente o contrato de interface antes da implementação.", "outcomes": [ "Um contrato de interface validado para o estilo de disponibilização selecionado", "Decisões consistentes sobre interação, dados, eventos, ficheiros, fluxos de trabalho ou contratos de API", "Rastreabilidade da conceção até aos requisitos da capacidade e dos consumidores", "Conceções alinhadas com modelos de domínio e padrões de interação" ], "steps": [ { "text": "Reutilize o Canvas de Domínio para confirmar objetos de negócio, termos, regras e propriedade antes da conceção do contrato.", "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas" }, { "text": "Utilize o Canvas de Interação para descrever como consumidores, sistemas ou utilizadores interagem com a capacidade.", "resourceId": "interactionCanvas", "resourceTitle": "Canvas de Interação", "canvasId": "interactionCanvas" }, { "text": "Utilize recursos de conceção REST quando a interface selecionada for uma API REST.", "resourceId": "restCanvas", "resourceTitle": "Canvas REST", "canvasId": "restCanvas" }, { "text": "Utilize recursos de Canvas de Eventos quando a interface selecionada for orientada por eventos.", "resourceId": "eventCanvas", "resourceTitle": "Canvas de Eventos", "canvasId": "eventCanvas" }, { "text": "Utilize recursos de conceção GraphQL quando a interface selecionada for GraphQL.", "resourceId": "graphqlCanvas", "resourceTitle": "Canvas GraphQL", "canvasId": "graphqlCanvas" }, { "text": "Utilize os princípios de conceção e a orientação de estilo para alinhar decisões de conceção com regras partilhadas e permitir validação de auditoria consistente.", "resourceId": "api-design-principles", "resourceTitle": "Princípios de conceção da API", "canvasId": null }, { "text": "Aplique abordagens contract-first ou design-first para captar e validar o contrato de interface antes da implementação.", "resourceId": "contract-first-design", "resourceTitle": "Primeira conceção do contrato", "canvasId": null }, { "text": "Utilize a lista de verificação de auditoria para garantir que a conceção cumpre requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "questions": [ "Reutilize o Canvas de Domínio para confirmar objetos de negócio, termos, regras e propriedade antes da conceção do contrato.", "Utilize o Canvas de Interação para descrever como consumidores, sistemas ou utilizadores interagem com a capacidade.", "Utilize recursos de conceção REST quando a interface selecionada for uma API REST.", "Utilize recursos de Canvas de Eventos quando a interface selecionada for orientada por eventos.", "Utilize recursos de conceção GraphQL quando a interface selecionada for GraphQL.", "Utilize os princípios de conceção e a orientação de estilo para alinhar decisões de conceção com regras partilhadas e permitir validação de auditoria consistente.", "Aplique abordagens contract-first ou design-first para captar e validar o contrato de interface antes da implementação.", "Utilize a lista de verificação de auditoria para garantir que a conceção cumpre requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Selecione os recursos de conceção adequados ao estilo de disponibilização escolhido e documente o contrato de interface antes da implementação.", "Depois de conhecido o padrão de arquitetura, a conceção deve transformar os requisitos da capacidade em contratos de interface, interações, esquemas, regras de dados, expectativas de ciclo de vida e obrigações dos consumidores claros." ], "criteria": [ "architecture-patterns-validated", "hide-backend-discrepancies", "design-reflects-business-value", "api-consistency" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." } ], "baseTitle": "Conceção da API - Conceber APIs que proporcionem valor", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "design", "stakeholders": [ { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "lead", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "core", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "core", "responsibilities": [] }, { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "consulted", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "contract-first-design", "slug": "resources/contract-first-design", "title": "Primeira conceção do contrato", "description": "Uma diretriz que defende abordagens API-first utilizando contratos formais (por exemplo, OpenAPI) para alinhar as partes interessadas antes do desenvolvimento.", "category": "guideline", "icon": "edit-document-outline", "order": 146, "outcomes": [ "Melhor compreensão dos princípios de conceção da primeira fase do contrato", "Abordagem normalizada utilizando a conceção orientada por contrato", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar." ], "canvasId": null, "sourcePath": "src/snippets/api-contract-example.yaml", "sourceUrl": null, "contentMarkdown": "openapi: 3.0.3\r\ninfo:\r\n title: Sample Catalog API\r\n version: 1.0.0\r\n description: |\r\n Starter example for a read-only APIOps Cycles API.\r\n This example keeps the contract audit-friendly and easy to extend.\r\nservers:\r\n - url: /v1\r\n description: Versioned API base path\r\ntags:\r\n - name: catalog\r\n description: Browse and search catalog items\r\npaths:\r\n /items:\r\n get:\r\n tags: [catalog]\r\n summary: List catalog items\r\n description: Returns a paginated list of public catalog items.\r\n operationId: listItems\r\n parameters:\r\n - $ref: \"#/components/parameters/searchTerm\"\r\n - $ref: \"#/components/parameters/categoryId\"\r\n - $ref: \"#/components/parameters/page\"\r\n - $ref: \"#/components/parameters/pageSize\"\r\n responses:\r\n \"200\":\r\n description: Item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n examples:\r\n default:\r\n value:\r\n data:\r\n - itemId: item-123\r\n slug: blue-widget\r\n name: Blue Widget\r\n status: published\r\n page:\r\n number: 1\r\n size: 20\r\n totalItems: 1\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"429\":\r\n $ref: \"#/components/responses/TooManyRequests\"\r\n /items/{itemId}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by id\r\n description: Returns a single public catalog item by opaque identifier.\r\n operationId: getItemById\r\n parameters:\r\n - $ref: \"#/components/parameters/itemId\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /items/by-slug/{slug}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by slug\r\n description: Returns a single item by public slug.\r\n operationId: getItemBySlug\r\n parameters:\r\n - $ref: \"#/components/parameters/slug\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /categories/{categoryId}/items:\r\n get:\r\n tags: [catalog]\r\n summary: List items in category\r\n description: Returns public items in a category.\r\n operationId: listItemsByCategory\r\n parameters:\r\n - $ref: \"#/components/parameters/categoryId\"\r\n responses:\r\n \"200\":\r\n description: Category item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\ncomponents:\r\n parameters:\r\n itemId:\r\n name: itemId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: item-123\r\n slug:\r\n name: slug\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9]+(?:-[a-z0-9]+)*$\"\r\n example: blue-widget\r\n categoryId:\r\n name: categoryId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: home-goods\r\n searchTerm:\r\n name: searchTerm\r\n in: query\r\n required: false\r\n schema:\r\n type: string\r\n minLength: 1\r\n example: widget\r\n page:\r\n name: page\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n default: 1\r\n pageSize:\r\n name: pageSize\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n maximum: 100\r\n default: 20\r\n responses:\r\n BadRequest:\r\n description: Validation failed\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n examples:\r\n default:\r\n value:\r\n code: BAD_REQUEST\r\n message: Invalid request\r\n NotFound:\r\n description: Resource not found\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n TooManyRequests:\r\n description: Rate limit exceeded\r\n headers:\r\n Retry-After:\r\n schema:\r\n type: integer\r\n description: Seconds until the next allowed request.\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n schemas:\r\n ItemListResponse:\r\n type: object\r\n required: [data, page]\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/ItemSummary\"\r\n page:\r\n $ref: \"#/components/schemas/Page\"\r\n ItemSummary:\r\n type: object\r\n required: [itemId, slug, name, status]\r\n properties:\r\n itemId:\r\n type: string\r\n slug:\r\n type: string\r\n name:\r\n type: string\r\n status:\r\n type: string\r\n enum: [published, hidden]\r\n ItemDetail:\r\n allOf:\r\n - $ref: \"#/components/schemas/ItemSummary\"\r\n - type: object\r\n properties:\r\n description:\r\n type: string\r\n categories:\r\n type: array\r\n items:\r\n type: string\r\n variants:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/Variant\"\r\n Variant:\r\n type: object\r\n required: [variantId, sku, price, inventory]\r\n properties:\r\n variantId:\r\n type: string\r\n sku:\r\n type: string\r\n price:\r\n $ref: \"#/components/schemas/Price\"\r\n inventory:\r\n $ref: \"#/components/schemas/Inventory\"\r\n Price:\r\n type: object\r\n required: [amount, currency]\r\n properties:\r\n amount:\r\n type: number\r\n format: decimal\r\n currency:\r\n type: string\r\n example: EUR\r\n Inventory:\r\n type: object\r\n required: [available]\r\n properties:\r\n available:\r\n type: integer\r\n minimum: 0\r\n reserved:\r\n type: integer\r\n minimum: 0\r\n source:\r\n type: string\r\n Page:\r\n type: object\r\n required: [number, size, totalItems]\r\n properties:\r\n number:\r\n type: integer\r\n size:\r\n type: integer\r\n totalItems:\r\n type: integer\r\n ErrorResponse:\r\n type: object\r\n required: [code, message]\r\n properties:\r\n code:\r\n type: string\r\n message:\r\n type: string\r\n", "draft": true } ], "evidence": [ "spec", "contract", "design-artifact", "documentation" ] }, { "index": 5, "id": "api-delivery", "slug": "method/api-delivery", "icon": "code", "title": "Entrega e operações", "description": "Construa, teste, disponibilize e opere a capacidade usando o estilo de disponibilização selecionado e o contrato de interface validado.", "whyItMatters": "Uma capacidade reutilizável precisa de entrega e operações fiáveis, quer se torne uma API, stream de eventos, troca de ficheiros, produto de dados ou integração direta.", "applyInWork": "Aplique orientação de entrega, testes, CI/CD, operações e segurança ao estilo de disponibilização escolhido.", "outcomes": [ "Uma capacidade entregue e alinhada com o contrato de interface validado", "Testes, disponibilização e controlos de ambiente automatizados", "Práticas de segurança, operações e qualidade adequadas ao padrão escolhido", "Controlos de entrega e disponibilização rastreáveis" ], "steps": [ { "text": "Utilize boas práticas de desenvolvimento para implementar o contrato de interface validado com frameworks, bibliotecas e normas da equipa estabelecidos.", "resourceId": "api-development-best-practices", "resourceTitle": "Boas práticas de desenvolvimento de API", "canvasId": null }, { "text": "Construa a implementação a partir do contrato de interface validado, usando frameworks, bibliotecas e normas da equipa estabelecidos.", "resourceId": "api-development-best-practices", "resourceTitle": "Boas práticas de desenvolvimento de API", "canvasId": null }, { "text": "Utilize orientação de testes para verificar funcionalidade, qualidade dos dados, compatibilidade, segurança, desempenho, resiliência e expectativas de recuperação.", "resourceId": "api-testing-best-practices", "resourceTitle": "Boas práticas de teste de API", "canvasId": null }, { "text": "Utilize orientação de CI/CD para automatizar construção, testes, disponibilização, configuração e rastreabilidade.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null }, { "text": "Utilize orientação de segurança para proteger dados, acesso, credenciais e fronteiras da plataforma.", "resourceId": "api-security-best-practices", "resourceTitle": "Boas práticas de segurança da API", "canvasId": null }, { "text": "Utilize a lista de verificação de auditoria para garantir que a solução cumpre requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "questions": [ "Utilize boas práticas de desenvolvimento para implementar o contrato de interface validado com frameworks, bibliotecas e normas da equipa estabelecidos.", "Construa a implementação a partir do contrato de interface validado, usando frameworks, bibliotecas e normas da equipa estabelecidos.", "Utilize orientação de testes para verificar funcionalidade, qualidade dos dados, compatibilidade, segurança, desempenho, resiliência e expectativas de recuperação.", "Utilize orientação de CI/CD para automatizar construção, testes, disponibilização, configuração e rastreabilidade.", "Utilize orientação de segurança para proteger dados, acesso, credenciais e fronteiras da plataforma.", "Utilize a lista de verificação de auditoria para garantir que a solução cumpre requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Aplique orientação de entrega, testes, CI/CD, operações e segurança ao estilo de disponibilização escolhido.", "Uma capacidade reutilizável precisa de entrega e operações fiáveis, quer se torne uma API, stream de eventos, troca de ficheiros, produto de dados ou integração direta." ], "criteria": [ "architecture-patterns-validated", "hide-backend-discrepancies", "design-reflects-business-value", "api-consistency" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." } ], "baseTitle": "Entrega da API - Fornecer APIs seguras e fiáveis", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "delivery", "stakeholders": [ { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "lead", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "api-development-best-practices", "slug": "resources/api-development-best-practices", "title": "Boas práticas de desenvolvimento de API", "description": "Orientações de implementação para transformar um contrato de interface da API validado numa base de código de API consistente e sustentável, utilizando bibliotecas padrão, padrões reutilizáveis e fluxos de trabalho de desenvolvimento alinhados.", "category": "guideline", "icon": "edit-document-outline", "order": 112, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de desenvolvimento de API", "Abordagem normalizada utilizando as boas práticas de desenvolvimento de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplique essas práticas ao contrato de interface da API validado e ao plano de implementação antes do início da codificação.", "Utilize frameworks, bibliotecas e padrões de codificação estabelecidos para implementar o contrato de forma consistente e sustentável." ], "canvasId": null, "sourcePath": "src/snippets/pt/api-design-principles-guidance.md", "sourceUrl": null, "contentMarkdown": "## Como iniciar o trabalho de entrega da API com base nas fases anteriores (“etapas”)\r\nUtilize estas orientações no início da `API Delivery` (entrega da API), após a revisão e aceitação do contrato da API (por exemplo, OpenAPI) e dos principais resultados das etapas anteriores.\r\nO objetivo não é desenvolver a implementação de forma isolada. O objetivo é transformar os resultados acordados nas etapas anteriores em uma estrutura de código concreta, regras de validação, comportamento em tempo de execução e decisões relativas à entrega do produto API.\r\n\r\n---\r\n\r\n### 1. Comece a partir do contrato validado\r\n- Trate o contrato de API validado como o principal ponto de referência para as decisões de implementação.\r\n- Mantenha o contrato e a implementação alinhados ao longo de toda a entrega do produto API.\r\n- Use o contrato para orientar a validação de solicitações, o mapeamento de respostas, a documentação e os testes.\r\n\r\n---\r\n\r\n### 2. Use os resultados do domínio para preservar o significado comercial\r\n- Use os resultados do `Domain Canvas` para orientar a nomenclatura, como a implementação é dividida em responsabilidades comerciais claras e como diferentes sistemas de back-end são conectados sem expor suas diferenças.\r\n- Preserve os significados validados de entidades, atributos, status e regras de fonte de verdade.\r\n- Evite vazar modelos específicos do back-end ou inconsistências para a API pública.\r\n\r\n---\r\n\r\n### 3. Use os resultados da jornada para preservar fluxos críticos\r\n- Use os resultados do `Customer Journey Canvas` para identificar quais fluxos de usuários são mais importantes para serem atendidos primeiro.\r\n- Use os resultados da `API Consumer Experience` para manter a API compreensível, previsível e fácil de integrar.\r\n- Deixe que as prioridades de jornada acordadas decidam quais caminhos de implementação precisam da maior confiabilidade, menor latência, erros mais claros e maior foco operacional.\r\n\r\n---\r\n\r\n### 4. Use os resultados da Proposta de Valor para preservar o valor para o consumidor\r\n- Use os resultados do `API Value Proposition Canvas` para manter a implementação focada nas dores, ganhos e recursos da API acordados.\r\n- Preserve os significados dos campos, o comportamento e as promessas que tornaram a API valiosa nas etapas anteriores.\r\n- Garanta que o tratamento de erros, a atualização e a nomenclatura apoiem tanto a experiência do desenvolvedor pretendida quanto o caso de uso de negócios.\r\n\r\n---\r\n\r\n### 5. Use os resultados da arquitetura para moldar as decisões de tempo de execução\r\n- Use os resultados do `Business Impact Canvas` para orientar as decisões sobre resiliência, tempo limite, fallback e degradação.\r\n- Use os resultados do `Locations Canvas` para orientar os limites de rede, limites de confiança, caminhos de acesso e restrições de implantação.\r\n- Use os resultados do `Capacity Canvas` para orientar limites de taxa, cache, escalonamento e comportamento em picos de carga.\r\n- Use as orientações do `API Metrics And Analytics` para decidir o que deve ser observado desde a primeira implementação em diante.\r\n\r\n---\r\n\r\n### 6. Use os resultados do projeto de interação e protocolo para moldar a estrutura do código\r\n- Use os resultados do `Interaction Canvas` para evitar implementar estilos de interação não suportados prematuramente.\r\n- Use os resultados do projeto `REST`, `Event` ou `GraphQL` para moldar o comportamento de solicitação, resposta e validação específico do protocolo.\r\n- Reflete o estilo de interação selecionado claramente na estrutura do código, nas responsabilidades e na estratégia de testes.\r\n\r\n---\r\n\r\n### 7. Usa os resultados da auditoria para melhorar a entrega antes que a codificação avance demais\r\n- Usa as conclusões da auditoria para remover ambiguidades antes que a implementação se espalhe pela base de código.\r\n- Corrige regras de solicitação pouco claras, validações ausentes, contratos de erro fracos e lacunas operacionais logo no início.\r\n- Trate a auditoria como um ciclo de melhoria de projeto antes da produção, não apenas como uma etapa de decisão final.\r\n\r\n---\r\n\r\n### 8. Aplique as orientações e, em seguida, resuma\r\n- Aplique estas orientações à API atual e ao plano de implementação.\r\n- Resuma as implicações para a estrutura do código, validação de solicitações, integração de fontes, segurança, monitoramento e alertas, e testes.\r\n- Não crie um artefato de entrega separado, a menos que a equipe ou o usuário precise especificamente de um.\r\n", "draft": true }, { "id": "api-testing-best-practices", "slug": "resources/api-testing-best-practices", "title": "Boas práticas de teste de API", "description": "Diretrizes para a implementação de testes automatizados funcionais, de desempenho e de segurança ao longo do ciclo de vida da API.", "category": "guideline", "icon": "edit-document-outline", "order": 133, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de teste de API", "Abordagem normalizada utilizando as boas práticas de teste de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Integrar testes funcionais e não funcionais no pipeline CI/CD para garantir que as APIs cumprems normas de qualidade.", "Utilizar ferramentas de teste automatizadas para validar a funcionalidade, a segurança e o desempenho da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "apiops-CI-CD-for-apis", "slug": "resources/apiops-CI-CD-for-apis", "title": "APIOps CI/CD para APIs", "description": "Orientação de disponibilização que integra tarefas do ciclo de vida da API - design, teste, governação - em pipelines de integração e entrega contínuas.", "category": "guideline", "icon": "edit-document-outline", "order": 140, "outcomes": [ "Melhor compreensão dos princípios de CI/CD para APIs", "Abordagem normalizada utilizando CI/CD para APIs", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilizar pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "implementation", "pipeline-config", "test-report", "security-report" ] }, { "index": 6, "id": "api-audit", "slug": "method/api-audit", "icon": "check-box-outline", "title": "Garantia de qualidade e prontidão", "description": "Audite o contrato de interface, os controlos, o modelo de suporte, a observabilidade, a documentação e a prontidão de ciclo de vida da capacidade antes da disponibilização.", "whyItMatters": "As capacidades reutilizáveis criam riscos operacionais, de dados, segurança, privacidade, conformidade e impacto nos consumidores. As verificações de prontidão reduzem surpresas antes da publicação ou utilização em produção.", "applyInWork": "Utilize recursos de auditoria e conformidade para verificar que a capacidade está pronta para disponibilização controlada e reutilização.", "outcomes": [ "Prontidão para disponibilização e reutilização documentada", "Lacunas e mitigações conhecidas antes da publicação", "Evidências para aprovação de governação, conformidade, suporte e operações", "Risco reduzido de problemas em produção" ], "steps": [ { "text": "Utilize a lista de verificação de auditoria como checklist de qualidade reutilizável para contrato de interface, documentação, segurança, desempenho e prontidão de conformidade.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null }, { "text": "Utilize checklists, linters e ferramentas de teste para verificar consistência e conformidade com normas.", "resourceId": "api-compliance-best-practices", "resourceTitle": "Boas práticas de conformidade da API", "canvasId": null }, { "text": "Colabore com equipas de governação e especialistas de domínio para garantir que a capacidade está pronta para produção.", "resourceTitle": "", "canvasId": null } ], "questions": [ "Utilize a lista de verificação de auditoria como checklist de qualidade reutilizável para contrato de interface, documentação, segurança, desempenho e prontidão de conformidade.", "Utilize checklists, linters e ferramentas de teste para verificar consistência e conformidade com normas.", "Colabore com equipas de governação e especialistas de domínio para garantir que a capacidade está pronta para produção.", "Utilize recursos de auditoria e conformidade para verificar que a capacidade está pronta para disponibilização controlada e reutilização.", "As capacidades reutilizáveis criam riscos operacionais, de dados, segurança, privacidade, conformidade e impacto nos consumidores. As verificações de prontidão reduzem surpresas antes da publicação ou utilização em produção." ], "criteria": [ "architecture-patterns-validated", "design-reflects-business-value", "api-description-available", "api-consistency", "api-contract-tested" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-description-available", "title": "A interface e as suas capacidades estão documentadas de forma suficientemente clara para revisão, auditoria e onboarding.", "description": "The API and its exposed capabilities are described clearly enough for review, audit, and onboarding." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." }, { "id": "api-contract-tested", "title": "O contrato de interface foi validado e testado face aos requisitos funcionais e não funcionais.", "description": "The API contract is tested and meets functional and non-functional requirements." } ], "baseTitle": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "publishing", "stakeholders": [ { "id": "governance-specialist", "sourceKey": "governance-specialist", "sourceStakeholderId": "governance-specialist", "title": "Responsável pela governação API", "description": "Representa práticas de revisão, auditoria e governação em toda a organização para qualidade e conformidade das APIs.", "involvement": "lead", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "consulted", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "api-audit-checklist", "slug": "resources/api-audit-checklist", "title": "Lista de verificação de auditoria da API", "description": "Uma lista de verificação baseada no ciclo de vida para verificar a prontidão da API em design, entrega, publicação e conformidade utilizando critérios de auditoria e evidências definidos.", "category": "checklist", "icon": "check-box-outline", "order": 13, "outcomes": [ "Melhor compreensão dos princípios da lista de controlo de auditoria da API", "Abordagem normalizada utilizando a lista de verificação de auditoria da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilize a lista de verificação de auditoria da API para garantir que a conceção da API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Realize auditorias para avaliar a cobertura do ciclo de vida e verificar se a API satisfaz os padrões de negócio, conceção e operacionais.", "Certifique-se de que a documentação, os modelos de segurança, a configuração do gateway e os requisitos legais estejam claramente definidos, validados e comprovados por evidências." ], "canvasId": null, "sourcePath": "src/snippets/api-audit-checklist.json", "sourceUrl": null, "contentMarkdown": "{\r\n \"profiles\": {\r\n \"read-only\": {\r\n \"description\": \"API profile that is read-only and does not allow create, update, or delete operations.\"\r\n },\r\n \"full-crud\": {\r\n \"description\": \"General API profile that allows create, update, and delete operations.\"\r\n }\r\n },\r\n \"lifecycleStages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6\r\n }\r\n ],\r\n \"stages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1,\r\n \"items\": [\r\n {\r\n \"id\": \"based-on-clear-business-needs\",\r\n \"label\": \"API is based on clear business needs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiBusinessModelCanvas\",\r\n \"apiValuePropositionCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"design-artifact\",\r\n \"documentation\",\r\n \"research\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\",\r\n \"specs/canvases/api-product-strategy/apiBusinessModelCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"concept-items-audited\",\r\n \"label\": \"All concept checklist items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"strategy\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\",\r\n \"api-opportunity-documented\",\r\n \"api-reusability\",\r\n \"value-prop-validated\",\r\n \"consumer-segments-identified\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/concept-review-report.json\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2,\r\n \"items\": [\r\n {\r\n \"id\": \"versioning-decided\",\r\n \"label\": \"Versioning strategy decided and supported by gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VERSION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-versioning-best-practices\",\r\n \"apiops-CI-CD-for-apis\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"ci-cd\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"only-via-gateway\",\r\n \"label\": \"Only accessible via API gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-02\",\r\n \"REST-CAPACITY-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"businessImpactCanvas\",\r\n \"locationsCanvas\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"infra-config\",\r\n \"security-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"rate-limits-enforced\",\r\n \"label\": \"Rate limits are enforced\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CAPACITY-01\",\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"capacityCanvas\",\r\n \"api-security-best-practices\",\r\n \"scalable-infrastructure-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"runtime\",\r\n \"monitoring\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-platform-architecture/capacityCanvas.empty.json\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3,\r\n \"items\": [\r\n {\r\n \"id\": \"endpoint-descriptions-present\",\r\n \"label\": \"Endpoints have business value and feature descriptions\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"operationDescriptions\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\",\r\n \"api-opportunity-documented\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiValuePropositionCanvas\",\r\n \"customerJourneyCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"hides-raw-backend-data\",\r\n \"label\": \"API hides raw backend data and is designed for shared use\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"interactionCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/domainCanvas.empty.json\",\r\n \"specs/canvases/api-design/interactionCanvas.empty.json\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"design-consistent\",\r\n \"label\": \"API design is consistent with other APIs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-02\",\r\n \"REST-CX-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-design/restCanvas.empty.json\",\r\n \"docs/api/design/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"descriptive-english-naming\",\r\n \"label\": \"Data and attribute naming uses descriptive English\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"fieldNamesDescriptive\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"mandatory-fields-specified\",\r\n \"label\": \"Mandatory fields are specified\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"requiredFieldsPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"dates-use-iso\",\r\n \"label\": \"Dates use ISO format with timezone\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"dateFormatTimezone\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"general-data-uses-standard-values\",\r\n \"label\": \"General data uses standard values\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"standardizedEnumsOrPatterns\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"field-names-avoid-acronyms\",\r\n \"label\": \"Field names avoid acronyms and use full words\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"avoidAcronyms\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"create-returns-identifiers\",\r\n \"label\": \"Creating new resources returns identifiers\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is read-only and does not create resources.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"paths-max-two-resources\",\r\n \"label\": \"Endpoint paths contain max two resources or sub-resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"pathDepthMax\",\r\n \"maxDepth\": 2\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PATH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"examples-present\",\r\n \"label\": \"Endpoints and attributes include examples\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-for-create-update\",\r\n \"label\": \"POST is used for create or update\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose create or update operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-for-remove\",\r\n \"label\": \"DELETE is used to remove resources\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose delete operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-no-request-body\",\r\n \"label\": \"GET has no request body and returns content\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"getNoRequestBody\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-empty-returns-204\",\r\n \"label\": \"GET returns 204 if response body is empty\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current contract returns content for all GET operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-200\",\r\n \"label\": \"POST returns 200 OK when updating\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST updates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-201\",\r\n \"label\": \"POST returns 201 Created with ID on create\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST creates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-returns-204\",\r\n \"label\": \"DELETE returns 204 on success\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose DELETE operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"400-errors-specific\",\r\n \"label\": \"400 errors provide specific error information\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"errorResponsesSpecific\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-400-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"api-audit-checklist\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"401-unauthorized\",\r\n \"label\": \"401 Unauthorized for wrong credentials\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current public storefront contract is intentionally unauthenticated.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-401-01\",\r\n \"REST-SEC-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"403-forbidden\",\r\n \"label\": \"403 Forbidden for unauthorized operations\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current profile is public read-only and exposes no unauthorized operations.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-403-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-contains-schemas\",\r\n \"label\": \"Spec contains request and response schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"schemasPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"restCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"pseudo-identifiers\",\r\n \"label\": \"UUIDs or pseudo-identifiers instead of DB IDs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"opaqueIdentifiers\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-07\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"no-sensitive-data-in-urls\",\r\n \"label\": \"No sensitive data in URLs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"noSensitiveDataInPaths\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-06\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"http-methods-match-resources\",\r\n \"label\": \"HTTP methods only for intended resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"methodResourceConsistency\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\",\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4,\r\n \"items\": [\r\n {\r\n \"id\": \"design-items-audited\",\r\n \"label\": \"All prototype and design items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"design\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"design-reflects-business-value\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/production-readiness-review.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-validated-on-change\",\r\n \"label\": \"Spec validated on every change\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"validationWorkflowPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\",\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"schema-and-examples-pass\",\r\n \"label\": \"Schema and examples pass validation\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPassValidation\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-contract-tested\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\",\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"api-audit-checklist\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"uses-https\",\r\n \"label\": \"Uses HTTPS or encrypted protocols\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"auth-protection\",\r\n \"label\": \"Endpoints protected by authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"token-auth\",\r\n \"label\": \"Token-based authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"csrf-protection\",\r\n \"label\": \"Protected against CSRF\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-08\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-development-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"inputs-auto-validated\",\r\n \"label\": \"Inputs auto-validated by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"contract-first-design\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\",\r\n \"test\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"outputs-auto-escaped\",\r\n \"label\": \"Outputs auto-escaped by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"JSON APIs do not typically require output escaping in the same way as HTML rendering.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"encryption-in-transit\",\r\n \"label\": \"Encryption for data in transit and storage\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"infra-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"message-integrity\",\r\n \"label\": \"Message integrity implemented\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"monitoring\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5,\r\n \"items\": [\r\n {\r\n \"id\": \"published-via-api-management\",\r\n \"label\": \"Published via API management\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"ci-cd\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"visible-in-dev-portal\",\r\n \"label\": \"Visible in developer portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-community-engagement-strategies\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"docs-auto-generated\",\r\n \"label\": \"Docs auto-generated from spec and schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\",\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"documentation\",\r\n \"ci-cd\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/publishing/README.md\",\r\n \"docs/api/audit/design-audit.read-only.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-auto-updated\",\r\n \"label\": \"Spec auto-updated to gateway and dev portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"contract-first-design\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"gateway-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"official-domain\",\r\n \"label\": \"Published under official organization domain\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6,\r\n \"items\": []\r\n }\r\n ],\r\n \"guidelines\": [\r\n {\r\n \"id\": \"REST-CONTRACT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST implement endpoints, parameters, request bodies, response bodies, and error responses as defined in the validated OpenAPI contract.\",\r\n \"relatedAuditItems\": [\r\n \"spec-contains-schemas\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CONTRACT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST keep the implementation, published OpenAPI description, gateway configuration, and developer portal documentation aligned on every change.\",\r\n \"relatedAuditItems\": [\r\n \"docs-auto-generated\",\r\n \"spec-auto-updated\",\r\n \"spec-validated-on-change\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VALIDATION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate path parameters, query parameters, headers, and JSON request bodies against the OpenAPI schema before business processing.\",\r\n \"relatedAuditItems\": [\r\n \"mandatory-fields-specified\",\r\n \"400-errors-specific\",\r\n \"inputs-auto-validated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST expose business-oriented resources and attributes rather than raw backend tables, internal service payloads, or system-specific field names.\",\r\n \"relatedAuditItems\": [\r\n \"based-on-clear-business-needs\",\r\n \"hides-raw-backend-data\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST preserve validated meanings of entities, attributes, statuses, and source-of-truth rules across all endpoints and operations.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\",\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use descriptive English names for resources and attributes.\",\r\n \"relatedAuditItems\": [\r\n \"descriptive-english-naming\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST avoid unexplained acronyms in public field and resource names.\",\r\n \"relatedAuditItems\": [\r\n \"field-names-avoid-acronyms\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use ISO date-time values with timezone information where dates are exposed.\",\r\n \"relatedAuditItems\": [\r\n \"dates-use-iso\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API SHOULD use standard codes, controlled vocabularies, and standardized value sets where applicable.\",\r\n \"relatedAuditItems\": [\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST describe the business value and feature intent of each endpoint or capability.\",\r\n \"relatedAuditItems\": [\r\n \"endpoint-descriptions-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST include examples for endpoints, request bodies, response bodies, and key attributes.\",\r\n \"relatedAuditItems\": [\r\n \"examples-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API SHOULD use consistent pagination, filtering, sorting, and response conventions across resources.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-GET-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use GET for safe read-only operations and MUST NOT define a request body for GET operations.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-POST-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use POST for resource creation and other non-idempotent operations.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-PUT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use PUT only for full resource replacement.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-DELETE-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use DELETE to remove resources.\",\r\n \"relatedAuditItems\": [\r\n \"delete-for-remove\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PATH-01\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"resource-modeling\",\r\n \"requirement\": \"The REST API SHOULD keep endpoint paths shallow and avoid more than two resource or sub-resource levels unless explicitly justified.\",\r\n \"relatedAuditItems\": [\r\n \"paths-max-two-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-200-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 200 OK for successful reads and updates that include a response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"post-returns-200\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-201-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 201 Created and the created resource identifier when a new resource is created.\",\r\n \"relatedAuditItems\": [\r\n \"create-returns-identifiers\",\r\n \"post-returns-201\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 204 No Content for successful delete operations that do not return a body.\",\r\n \"relatedAuditItems\": [\r\n \"delete-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API SHOULD return 204 No Content for successful operations that intentionally return no response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-empty-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-400-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST define 400 Bad Request responses with specific and actionable validation error information.\",\r\n \"relatedAuditItems\": [\r\n \"400-errors-specific\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-401-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 401 Unauthorized for missing or invalid credentials.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-403-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 403 Forbidden for authenticated clients lacking sufficient permission.\",\r\n \"relatedAuditItems\": [\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VERSION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"versioning\",\r\n \"requirement\": \"The REST API MUST define a versioning strategy before production release, and the strategy MUST be supportable by the API gateway.\",\r\n \"relatedAuditItems\": [\r\n \"versioning-decided\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST require authentication for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use token-based authentication or another approved modern authentication mechanism for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"token-auth\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-03\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST enforce object-level and function-level authorization on every protected operation.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\",\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST mitigate OWASP API risks including broken object level authorization, broken function level authorization, injection, and unrestricted resource consumption.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"rate-limits-enforced\",\r\n \"no-sensitive-data-in-urls\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-05\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use HTTPS or another approved encrypted protocol for all traffic.\",\r\n \"relatedAuditItems\": [\r\n \"uses-https\",\r\n \"encryption-in-transit\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-06\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST NOT expose sensitive information in URLs, query strings, logs, or unnecessary response fields.\",\r\n \"relatedAuditItems\": [\r\n \"no-sensitive-data-in-urls\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-07\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API SHOULD use UUIDs or other non-sequential public identifiers where direct database identifiers would increase exposure risk.\",\r\n \"relatedAuditItems\": [\r\n \"pseudo-identifiers\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-08\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST implement CSRF protection where relevant to the authentication model and client interaction pattern.\",\r\n \"relatedAuditItems\": [\r\n \"csrf-protection\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST define and enforce rate limits, throttling, or quotas according to capacity expectations.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST implement resilience controls such as timeouts, fallback behavior, and degradation handling according to business impact.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-OBS-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"observability\",\r\n \"requirement\": \"The REST API MUST implement logs, metrics, and monitoring needed to observe validation failures, auth failures, traffic, latency, and dependency health.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published through an API management platform.\",\r\n \"relatedAuditItems\": [\r\n \"published-via-api-management\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be accessible only through approved API gateway paths and managed entry points.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API SHOULD be visible in a developer portal with documentation generated from the contract.\",\r\n \"relatedAuditItems\": [\r\n \"visible-in-dev-portal\",\r\n \"docs-auto-generated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published under an approved organizational domain.\",\r\n \"relatedAuditItems\": [\r\n \"official-domain\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate the specification, schema, and examples on every change.\",\r\n \"relatedAuditItems\": [\r\n \"spec-validated-on-change\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST pass concept, design, security, and production-readiness checks before release.\",\r\n \"relatedAuditItems\": [\r\n \"concept-items-audited\",\r\n \"design-items-audited\"\r\n ]\r\n }\r\n ]\r\n}\r\n", "draft": false }, { "id": "api-compliance-best-practices", "slug": "resources/api-compliance-best-practices", "title": "Boas práticas de conformidade da API", "description": "Garantir que as APIs cumprem conformidade legal, regulamentar e interna através de documentação, controlos e validações automatizadas.", "category": "guideline", "icon": "edit-document-outline", "order": 104, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de conformidade da API", "Abordagem normalizada utilizando as Melhores Práticas de Conformidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Documentar as medidas de conformidade e garantir que são comunicadas às partes interessadas e aos utilizadores.", "Implementar medidas para garantir que as APIs cumprem estes requisitos, incluindo encriptação de dados, controlos de acesso e pistas de auditoria.", "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "audit-report", "compliance-report", "security-report", "test-report" ] }, { "index": 7, "id": "api-publishing", "slug": "method/api-publishing", "icon": "deployed-code-outline", "title": "Publicacao e enablement", "description": "Publique informação sobre a capacidade reutilizável para que os consumidores a possam descobrir, solicitar, integrar, utilizar e obter suporte.", "whyItMatters": "As capacidades reutilizáveis só criam valor quando os consumidores as conseguem encontrar, compreender o respetivo contrato de interface e expectativas de serviço, solicitar acesso e saber quem é responsável pelo suporte e pelas decisões de ciclo de vida.", "applyInWork": "Publique propriedade, documentação, integração, contactos de suporte, expectativas de serviço, estado de ciclo de vida e caminhos para pedidos de acesso.", "outcomes": [ "Uma capacidade reutilizável detetável", "Expectativas claras de integração, acesso, suporte e serviço", "Informação de ciclo de vida e propriedade disponível para consumidores e equipas de governação", "Consumidores capacitados para utilizar e reutilizar a capacidade" ], "steps": [ { "text": "Publique informação sobre a capacidade nos catálogos, portais, gateways ou ambientes adequados para apoiar a reutilização por vários consumidores.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null }, { "text": "Documente como os consumidores encontram e utilizam a capacidade, incluindo processos de integração e registo.", "resourceId": "api-onboarding-best-practices", "resourceTitle": "Boas práticas de integração de API", "canvasId": null }, { "text": "Garanta que os modelos de segurança, a configuração de acesso e os termos legais são claros e acessíveis aos consumidores.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "questions": [ "Publique informação sobre a capacidade nos catálogos, portais, gateways ou ambientes adequados para apoiar a reutilização por vários consumidores.", "Documente como os consumidores encontram e utilizam a capacidade, incluindo processos de integração e registo.", "Garanta que os modelos de segurança, a configuração de acesso e os termos legais são claros e acessíveis aos consumidores.", "Publique propriedade, documentação, integração, contactos de suporte, expectativas de serviço, estado de ciclo de vida e caminhos para pedidos de acesso.", "As capacidades reutilizáveis só criam valor quando os consumidores as conseguem encontrar, compreender o respetivo contrato de interface e expectativas de serviço, solicitar acesso e saber quem é responsável pelo suporte e pelas decisões de ciclo de vida." ], "criteria": [ "audit-passed", "audit-reports-shared", "api-ready-for-publishing", "api-documentation-ready" ], "criteriaDetails": [ { "id": "audit-passed", "title": "A solução passa as verificações de qualidade, segurança, conformidade e prontidão.", "description": "The API passes compliance, security, and audit checks." }, { "id": "audit-reports-shared", "title": "As conclusões da auditoria e as decisões de correção são partilhadas com as partes interessadas relevantes.", "description": "Audit findings and remediation decisions are shared with the relevant stakeholders." }, { "id": "api-ready-for-publishing", "title": "A capacidade está pronta para ser publicada ou disponibilizada através do mecanismo de entrega selecionado.", "description": "The API is ready to be deployed and exposed through the intended gateways and environments." }, { "id": "api-documentation-ready", "title": "A documentação orientada para os utilizadores e os materiais de onboarding estão prontos.", "description": "Consumer-facing API documentation is complete enough for publishing and onboarding." } ], "baseTitle": "Publicação de API - Publique APIs com confiança", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "publishing", "stakeholders": [ { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "lead", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "consulted", "responsibilities": [] }, { "id": "partner-specialist", "sourceKey": "partner-specialist", "sourceStakeholderId": "partner-specialist", "title": "Gestor de parceiros ou fornecedores", "description": "Coordena relações com parceiros, fornecedores ou prestadores externos que influenciam a estratégia e entrega da capacidade ou API.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "service-agreement-template", "slug": "resources/service-agreement-template", "title": "Modelo de contrato de serviço", "description": "Um formato de acordo personalizável que define expectativas, SLAs, responsabilidades e termos de acesso para o consumo de API.", "category": "guideline", "icon": "edit-document-outline", "order": 172, "outcomes": [ "Melhor compreensão dos princípios do modelo de contrato de prestação de serviços", "Abordagem normalizada utilizando o modelo de contrato de serviços", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Defina acordos de serviço que descrevam as expectativas, os níveis de serviço e as responsabilidades de cada API.", "Utilize formatos normalizados para criar contratos de serviço legíveis por máquina que sejam fáceis de partilhar e validar.", "Assegurar que os acordos de serviço são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "gateway-config", "developer-portal", "documentation", "release-record" ] }, { "index": 8, "id": "monitoring-and-improving", "slug": "method/monitoring-and-improving", "icon": "analytics-outline", "title": "Monitorização e melhoria", "description": "Monitorize a utilização, fiabilidade, qualidade dos dados, resultados dos consumidores, custo operacional e oportunidades de reutilização após a disponibilização.", "whyItMatters": "As capacidades precisam de feedback contínuo para permanecerem fiáveis, valiosas, rentáveis e reutilizáveis à medida que consumidores, sistemas, dados e plataformas mudam.", "applyInWork": "Utilize práticas de métricas, análise e envolvimento para melhorar a capacidade ao longo do tempo.", "outcomes": [ "Saúde e valor da capacidade medidos", "Backlog de melhorias informado por feedback operacional e dos consumidores", "Sinais de reutilização, fiabilidade, qualidade dos dados e custo disponíveis para os responsáveis", "Melhoria contínua alinhada com as necessidades dos consumidores" ], "steps": [ { "text": "Utilize orientação de métricas e análise para definir medidas de utilização da capacidade, fiabilidade, qualidade dos dados, custo, adoção e valor para os consumidores.", "resourceId": "api-metrics-and-analytics", "resourceTitle": "Métricas e análise de API", "canvasId": null }, { "text": "Analise métricas de utilização e incorpore feedback dos consumidores nas iterações da capacidade.", "resourceId": "api-community-engagement-strategies", "resourceTitle": "Estratégias de envolvimento da comunidade API", "canvasId": null }, { "text": "Estabeleça o hábito de rever métricas e planear atividades de melhoria contínua.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null } ], "questions": [ "Utilize orientação de métricas e análise para definir medidas de utilização da capacidade, fiabilidade, qualidade dos dados, custo, adoção e valor para os consumidores.", "Analise métricas de utilização e incorpore feedback dos consumidores nas iterações da capacidade.", "Estabeleça o hábito de rever métricas e planear atividades de melhoria contínua.", "Utilize práticas de métricas, análise e envolvimento para melhorar a capacidade ao longo do tempo.", "As capacidades precisam de feedback contínuo para permanecerem fiáveis, valiosas, rentáveis e reutilizáveis à medida que consumidores, sistemas, dados e plataformas mudam." ], "criteria": [ "api-documentation-ready", "consumer-support-ready", "legal-compliance-clear" ], "criteriaDetails": [ { "id": "api-documentation-ready", "title": "A documentação orientada para os utilizadores e os materiais de onboarding estão prontos.", "description": "Consumer-facing API documentation is complete enough for publishing and onboarding." }, { "id": "consumer-support-ready", "title": "Os processos de onboarding, suporte e comunicação para utilizadores estão prontos.", "description": "Registration, support, and communication processes are ready for API consumers." }, { "id": "legal-compliance-clear", "title": "Os requisitos legais, de privacidade e de conformidade para publicação ou disponibilização estão definidos e compreendidos.", "description": "Legal, privacy, and compliance requirements for publishing are defined and understood." } ], "baseTitle": "Monitorização e melhoria - para valor API", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "improving", "stakeholders": [ { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "lead", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "api-metrics-and-analytics", "slug": "resources/api-metrics-and-analytics", "title": "Métricas e análise de API", "description": "Um recurso para definir, recolher e analisar o desempenho da API e os dados de utilização para alinhar os KPIs técnicos com os resultados de negócio.", "category": "guideline", "icon": "edit-document-outline", "order": 119, "outcomes": [ "Melhor compreensão dos princípios de métrica e análise de API", "Abordagem normalizada utilizando métricas e análise de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação" ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-community-engagement-strategies", "slug": "resources/api-community-engagement-strategies", "title": "Estratégias de envolvimento da comunidade API", "description": "Um manual para promover a adoção de APIs, cultivando comunidades através de conteúdos, canais de apoio, ciclos de feedback e estratégias de envolvimento social.", "category": "guideline", "icon": "edit-document-outline", "order": 103, "outcomes": [ "Melhor compreensão dos princípios das estratégias de envolvimento da comunidade da API", "Abordagem normalizada utilizando as estratégias de envolvimento da comunidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Desenvolver estratégias de marketing para promover as APIs junto de públicos-alvo, incluindo redes sociais, blogues e webinars.", "Criar materiais promocionais (por exemplo, estudos de casos, histórias de sucesso) que realcem o valor e as vantagens das APIs.", "Criar materiais educativos (por exemplo, tutoriais, documentação) que expliquem as características, as vantagens e os padrões de utilização da API.", "Interagir com os utilizadores da API através de ciclos de feedback, canais de apoio e fóruns da comunidade para compreender as suas necessidades e melhorar a adoção da API.", "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "metrics", "consumer-feedback", "incident-report", "roadmap" ] } ] }, { "id": "api-productization-cycle", "slug": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las.", "purpose": "Jornada do metodo focada em API para equipas que ja sabem que o estilo de implementacao pretendido e um produto API.", "audiences": [], "audienceStakeholders": [ { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "lead", "responsibilities": [ { "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas", "role": "suggested-answer-owner" }, { "resourceId": "apiBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da API", "canvasId": "apiBusinessModelCanvas", "role": "suggested-answer-owner" } ] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [ { "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "role": "suggested-answer-owner" } ] }, { "id": "customer-specialist", "sourceKey": "customer-specialist", "sourceStakeholderId": "customer-specialist", "title": "Representante de cliente ou parceiro", "description": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "involvement": "core", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [ { "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "role": "suggested-answer-owner" } ] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "lead", "responsibilities": [] }, { "id": "api-architect", "sourceKey": "api-architect", "sourceStakeholderId": "api-architect", "title": "Arquiteto API", "description": "Responsável pela arquitetura API, pelos princípios de desenho e pela qualidade dos contratos de interface.", "involvement": "core", "responsibilities": [ { "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "role": "suggested-answer-owner" }, { "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas", "role": "suggested-answer-owner" } ] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "lead", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "lead", "responsibilities": [] }, { "id": "governance-specialist", "sourceKey": "governance-specialist", "sourceStakeholderId": "governance-specialist", "title": "Responsável pela governação API", "description": "Representa práticas de revisão, auditoria e governação em toda a organização para qualidade e conformidade das APIs.", "involvement": "lead", "responsibilities": [] } ], "entryCriteria": [ "api-opportunity-documented", "consumer-segments-identified" ], "exitCriteria": [ "api-contract-tested", "api-ready-for-publishing", "api-documentation-ready" ], "entryCriteriaDetails": [ { "id": "api-opportunity-documented", "title": "A oportunidade de capacidade está identificada e documentada.", "description": "Individual API opportunities are identified and documented." }, { "id": "consumer-segments-identified", "title": "Os segmentos de utilizadores estão identificados.", "description": "API consumer segments (internal and external) are identified." } ], "exitCriteriaDetails": [ { "id": "api-contract-tested", "title": "O contrato de interface foi validado e testado face aos requisitos funcionais e não funcionais.", "description": "The API contract is tested and meets functional and non-functional requirements." }, { "id": "api-ready-for-publishing", "title": "A capacidade está pronta para ser publicada ou disponibilizada através do mecanismo de entrega selecionado.", "description": "The API is ready to be deployed and exposed through the intended gateways and environments." }, { "id": "api-documentation-ready", "title": "A documentação orientada para os utilizadores e os materiais de onboarding estão prontos.", "description": "Consumer-facing API documentation is complete enough for publishing and onboarding." } ], "questionnaireResources": [ { "stationId": "api-product-strategy", "stationTitle": "Estratégia de produto API", "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas", "suggestedAnswerOwner": { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "lead", "responsibilities": [ { "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas", "role": "suggested-answer-owner" }, { "resourceId": "apiBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da API", "canvasId": "apiBusinessModelCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-product-strategy", "stationTitle": "Estratégia de produto API", "resourceId": "apiBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da API", "canvasId": "apiBusinessModelCanvas", "suggestedAnswerOwner": { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "lead", "responsibilities": [ { "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas", "role": "suggested-answer-owner" }, { "resourceId": "apiBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da API", "canvasId": "apiBusinessModelCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-product-strategy", "stationTitle": "Estratégia de produto API", "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "suggestedAnswerOwner": { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [ { "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-product-strategy", "stationTitle": "Estratégia de produto API", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "suggestedAnswerOwner": { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [ { "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-platform-architecture", "stationTitle": "Arquitetura da plataforma API", "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "suggestedAnswerOwner": { "id": "api-architect", "sourceKey": "api-architect", "sourceStakeholderId": "api-architect", "title": "Arquiteto API", "description": "Responsável pela arquitetura API, pelos princípios de desenho e pela qualidade dos contratos de interface.", "involvement": "core", "responsibilities": [ { "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "role": "suggested-answer-owner" }, { "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-platform-architecture", "stationTitle": "Arquitetura da plataforma API", "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas", "suggestedAnswerOwner": { "id": "api-architect", "sourceKey": "api-architect", "sourceStakeholderId": "api-architect", "title": "Arquiteto API", "description": "Responsável pela arquitetura API, pelos princípios de desenho e pela qualidade dos contratos de interface.", "involvement": "core", "responsibilities": [ { "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "role": "suggested-answer-owner" }, { "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-platform-architecture", "stationTitle": "Arquitetura da plataforma API", "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas", "suggestedAnswerOwner": { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "core", "responsibilities": [ { "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas", "role": "suggested-answer-owner" } ] } } ], "stations": [ { "index": 1, "id": "api-product-strategy", "slug": "method/api-product-strategy", "icon": "strategy-outline", "title": "Estratégia de produto API", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia.", "whyItMatters": "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais.", "applyInWork": "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "outcomes": [ "Uma proposta de valor e um público-alvo da API simples", "Linguagem partilhada entre o produto, a conceção e a tecnologia", "Um argumento sólido ou um caso para financiamento/aprovação" ], "steps": [ { "text": "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas" }, { "text": "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas" }, { "text": "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas" }, { "text": "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "resourceId": "apiBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da API", "canvasId": "apiBusinessModelCanvas" } ], "questions": [ "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais." ], "criteria": [ "metrics-feedback-available", "business-goals-defined", "market-research-done", "stakeholder-approval" ], "criteriaDetails": [ { "id": "metrics-feedback-available", "title": "Sinais de mercado relevantes, feedback ou conhecimento operacional estão disponíveis para orientar esta oportunidade de capacidade.", "description": "Relevant market signals, feedback, or operational insights are available to guide this API opportunity." }, { "id": "business-goals-defined", "title": "Os objetivos de negócio estão definidos.", "description": "Business goals are defined." }, { "id": "market-research-done", "title": "A investigação de mercado identifica oportunidades de capacidade.", "description": "Market research identifies API opportunities." }, { "id": "stakeholder-approval", "title": "As partes interessadas relevantes concordam que vale a pena explorar e priorizar esta oportunidade de capacidade.", "description": "Relevant stakeholders agree this API opportunity is worth exploring and prioritizing." } ], "baseTitle": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "strategy", "stakeholders": [ { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "lead", "responsibilities": [ { "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas", "role": "suggested-answer-owner" }, { "resourceId": "apiBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da API", "canvasId": "apiBusinessModelCanvas", "role": "suggested-answer-owner" } ] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [ { "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "role": "suggested-answer-owner" } ] }, { "id": "customer-specialist", "sourceKey": "customer-specialist", "sourceStakeholderId": "customer-specialist", "title": "Representante de cliente ou parceiro", "description": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "involvement": "core", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [ { "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "role": "suggested-answer-owner" } ] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "apiValuePropositionCanvas", "slug": "resources/api-value-proposition-canvas", "title": "Canvas da Proposta de Valor da API", "description": "Alinhar as funcionalidades da API com as necessidades dos utilizadores, mapeando tarefas, problemas e ganhos para os produtos da API.", "category": "canvas", "icon": "dashboard-outline", "order": 2, "outcomes": [ "Desenvolvimento de funcionalidades específicas", "Alinhamento com as necessidades dos utilizadores", "Melhoria da satisfação do utilizador da API" ], "steps": [ "Listar as tarefas do percurso do utilizador", "Identificar as características que proporcionam os ganhos esperados", "Definir características para enfrentar os desafios", "Mapear características para produtos API" ], "canvasId": "apiValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "apiBusinessModelCanvas", "slug": "resources/api-business-model-canvas", "title": "Canvas do Modelo de Negócio da API", "description": "Avaliar estrategicamente a viabilidade do negócio de API, mapeando propostas de valor, segmentos de utilizadores e recursos-chave.", "category": "canvas", "icon": "dashboard-outline", "order": 3, "outcomes": [ "Estratégia comercial clara para APIs", "Identificação dos principais recursos e parceiros", "Alinhamento das características da API com os objetivos de negócio" ], "steps": [ "Resumir a proposta de valor da API", "Definir segmentos de utilizadores", "Identificar estratégias de relações com os promotores", "Mapear os canais de distribuição", "documentar os principais recursos e actividades", "Identificar os principais parceiros e partes interessadas", "Destacar os benefícios e os custos" ], "canvasId": "apiBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false } ], "evidence": [ "design-artifact", "documentation", "research", "roadmap" ] }, { "index": 2, "id": "api-consumer-experience", "slug": "method/api-consumer-experience", "icon": "deployed-code-account-outline", "title": "Experiência do consumidor da API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento.", "whyItMatters": "As APIs excelentes não funcionam apenas - elas são intuitivas. Quer o consumidor seja um programador interno, um parceiro externo ou um agente de IA, a sua experiência determina a adoção.\n\nSnum plano de experiência claro:\n- Grandes APIs ficam sem uso\n- As equipas perdem tempo a tentar adivinhar como utilizar a sua API\n- Os ciclos de feedback estão quebrados ou ausentes.\n\nEsta estação ajuda-o a ver a sua API através dos olhos dos seus consumidores.", "applyInWork": "Fornecer diretrizes, ferramentas e mecanismos de feedback para compreender, analisar e melhorar a experiência interna e externa dos programadores e parceiros.", "outcomes": [ "Identifique e dê prioridade aos seus consumidores de API", "Definir o percurso da experiência API", "Planeamento da integração, documentação e feedback", "Melhorar a adoção através de empatia genuína + Experiência do Programador (DX)" ], "steps": [ { "text": "Analise o Canvas da Proposta de Valor da API existente sob a perspectiva do consumidor da API. Mantenha as tarefas de negócios suportadas estáveis ​​e enriqueça os recursos que aliviam problemas e possibilitam ganhos com as preocupações do consumidor da API, para que elas possam orientar as decisões de conceção futuras.", "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas" }, { "text": "Utilize o Canvas do Percurso do Cliente para a jornada do consumidor da API, desde a descoberta e avaliação até a integração, resolução de problemas e uso contínuo.", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas" }, { "text": "Utilize a jornada resultante para melhorar a integração, a documentação, o suporte e os ciclos de feedback para o consumidor da API.", "resourceId": "api-onboarding-best-practices", "resourceTitle": "Boas práticas de integração de API", "canvasId": null } ], "questions": [ "Analise o Canvas da Proposta de Valor da API existente sob a perspectiva do consumidor da API. Mantenha as tarefas de negócios suportadas estáveis ​​e enriqueça os recursos que aliviam problemas e possibilitam ganhos com as preocupações do consumidor da API, para que elas possam orientar as decisões de conceção futuras.", "Utilize o Canvas do Percurso do Cliente para a jornada do consumidor da API, desde a descoberta e avaliação até a integração, resolução de problemas e uso contínuo.", "Utilize a jornada resultante para melhorar a integração, a documentação, o suporte e os ciclos de feedback para o consumidor da API.", "Fornecer diretrizes, ferramentas e mecanismos de feedback para compreender, analisar e melhorar a experiência interna e externa dos programadores e parceiros.", "As APIs excelentes não funcionam apenas - elas são intuitivas. Quer o consumidor seja um programador interno, um parceiro externo ou um agente de IA, a sua experiência determina a adoção.\n\nSnum plano de experiência claro:\n- Grandes APIs ficam sem uso\n- As equipas perdem tempo a tentar adivinhar como utilizar a sua API\n- Os ciclos de feedback estão quebrados ou ausentes.\n\nEsta estação ajuda-o a ver a sua API através dos olhos dos seus consumidores." ], "criteria": [ "api-opportunity-documented", "api-reusability", "hide-backend-discrepancies", "value-prop-validated", "consumer-segments-identified", "api-roadmap-defined" ], "criteriaDetails": [ { "id": "api-opportunity-documented", "title": "A oportunidade de capacidade está identificada e documentada.", "description": "Individual API opportunities are identified and documented." }, { "id": "api-reusability", "title": "A capacidade responde a uma necessidade clara de negócio e é reutilizável pelos utilizadores previstos.", "description": "The API meets a clear business need and is reusable for multiple API consumers." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "value-prop-validated", "title": "A proposta de valor da capacidade foi validada com partes interessadas de negócio e utilizadores.", "description": "The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders." }, { "id": "consumer-segments-identified", "title": "Os segmentos de utilizadores estão identificados.", "description": "API consumer segments (internal and external) are identified." }, { "id": "api-roadmap-defined", "title": "Está definido um roadmap de implementação de alto nível.", "description": "High-level roadmaps for API development are established." } ], "baseTitle": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "strategy", "stakeholders": [ { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "lead", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "core", "responsibilities": [] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "apiValuePropositionCanvas", "slug": "resources/api-value-proposition-canvas", "title": "Canvas da Proposta de Valor da API", "description": "Alinhar as funcionalidades da API com as necessidades dos utilizadores, mapeando tarefas, problemas e ganhos para os produtos da API.", "category": "canvas", "icon": "dashboard-outline", "order": 2, "outcomes": [ "Desenvolvimento de funcionalidades específicas", "Alinhamento com as necessidades dos utilizadores", "Melhoria da satisfação do utilizador da API" ], "steps": [ "Listar as tarefas do percurso do utilizador", "Identificar as características que proporcionam os ganhos esperados", "Definir características para enfrentar os desafios", "Mapear características para produtos API" ], "canvasId": "apiValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "design-artifact", "documentation", "consumer-feedback" ] }, { "index": 3, "id": "api-platform-architecture", "slug": "method/api-platform-architecture", "icon": "code-blocks-outline", "title": "Arquitetura da plataforma API", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma.", "whyItMatters": "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência.", "applyInWork": "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "outcomes": [ "Corte APIs redundantes e reduza os custos da plataforma de nuvem", "Implementar uma governação consistente snum forte controlo do topo para a base", "Conceção para reutilização interna e escalabilidade externa" ], "steps": [ { "text": "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas" }, { "text": "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas" }, { "text": "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas" }, { "text": "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "resourceId": "api-metrics-and-analytics", "resourceTitle": "Métricas e análise de API", "canvasId": null } ], "questions": [ "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência." ], "criteria": [ "api-reusability", "hide-backend-discrepancies", "value-prop-validated", "consumer-segments-identified", "api-roadmap-defined" ], "criteriaDetails": [ { "id": "api-reusability", "title": "A capacidade responde a uma necessidade clara de negócio e é reutilizável pelos utilizadores previstos.", "description": "The API meets a clear business need and is reusable for multiple API consumers." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "value-prop-validated", "title": "A proposta de valor da capacidade foi validada com partes interessadas de negócio e utilizadores.", "description": "The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders." }, { "id": "consumer-segments-identified", "title": "Os segmentos de utilizadores estão identificados.", "description": "API consumer segments (internal and external) are identified." }, { "id": "api-roadmap-defined", "title": "Está definido um roadmap de implementação de alto nível.", "description": "High-level roadmaps for API development are established." } ], "baseTitle": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "architecture", "stakeholders": [ { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "lead", "responsibilities": [] }, { "id": "api-architect", "sourceKey": "api-architect", "sourceStakeholderId": "api-architect", "title": "Arquiteto API", "description": "Responsável pela arquitetura API, pelos princípios de desenho e pela qualidade dos contratos de interface.", "involvement": "core", "responsibilities": [ { "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "role": "suggested-answer-owner" }, { "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas", "role": "suggested-answer-owner" } ] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "core", "responsibilities": [ { "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas", "role": "suggested-answer-owner" } ] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-metrics-and-analytics", "slug": "resources/api-metrics-and-analytics", "title": "Métricas e análise de API", "description": "Um recurso para definir, recolher e analisar o desempenho da API e os dados de utilização para alinhar os KPIs técnicos com os resultados de negócio.", "category": "guideline", "icon": "edit-document-outline", "order": 119, "outcomes": [ "Melhor compreensão dos princípios de métrica e análise de API", "Abordagem normalizada utilizando métricas e análise de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação" ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "architecture-decision", "documentation", "platform-config", "metrics" ] }, { "index": 4, "id": "api-design", "slug": "method/api-design", "icon": "api", "title": "Conceção da API", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados.", "whyItMatters": "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.", "applyInWork": "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": [ { "text": "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs.", "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas" }, { "text": "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.", "resourceId": "interactionCanvas", "resourceTitle": "Canvas de Interação", "canvasId": "interactionCanvas" }, { "text": "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.", "resourceId": "restCanvas", "resourceTitle": "Canvas REST", "canvasId": "restCanvas" }, { "text": "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.", "resourceId": "eventCanvas", "resourceTitle": "Canvas de Eventos", "canvasId": "eventCanvas" }, { "text": "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.", "resourceId": "graphqlCanvas", "resourceTitle": "Canvas GraphQL", "canvasId": "graphqlCanvas" }, { "text": "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.", "resourceId": "api-design-principles", "resourceTitle": "Princípios de conceção da API", "canvasId": null }, { "text": "Aplique abordagens do tipo ‘contrato primeiro’ ou ‘design primeiro’ para capturar e validar o contrato de interface da API antes da implementação.", "resourceId": "contract-first-design", "resourceTitle": "Primeira conceção do contrato", "canvasId": null }, { "text": "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.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "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." ], "criteria": [ "architecture-patterns-validated", "hide-backend-discrepancies", "design-reflects-business-value", "api-consistency" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." } ], "baseTitle": "Conceção da API - Conceber APIs que proporcionem valor", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "design", "stakeholders": [ { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "lead", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "restCanvas", "slug": "resources/rest-canvas", "title": "Canvas REST", "description": "Conceber APIs utilizando os princípios RESTful, definindo recursos, verbos e exemplos de pedidos e respostas.", "category": "canvas", "icon": "dashboard-outline", "order": 10, "outcomes": [ "Conceção consistente da API RESTful", "Recursos definidos e suas interações", "Exemplos de pedidos e respostas para maior clareza" ], "steps": [ "Identificar os principais recursos expostos pela API", "Definir a estrutura do modelo de recursos da API", "Especificar os verbos HTTP utilizados para interagir com os recursos", "Fornecer exemplos de pedidos e respostas para cada verbo" ], "canvasId": "restCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "eventCanvas", "slug": "resources/event-canvas", "title": "Canvas de Eventos", "description": "Conceber APIs orientadas para eventos, definindo eventos, accionadores e lógica de processamento.", "category": "canvas", "icon": "dashboard-outline", "order": 12, "outcomes": [ "Arquitetura orientada para eventos definida", "Limpar os accionadores de eventos e a lógica de processamento", "Melhoria da capacidade de resposta a alterações em tempo real" ], "steps": [ "Identificar os principais eventos do sistema", "Definir accionadores para cada evento", "Descrever a lógica de processamento back-end para eventos", "Especificar os resultados ou reconhecimentos resultantes" ], "canvasId": "eventCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "graphqlCanvas", "slug": "resources/graphql-canvas", "title": "Canvas GraphQL", "description": "Conceber APIs GraphQL definindo tipos, consultas, mutações e subscrições.", "category": "canvas", "icon": "dashboard-outline", "order": 11, "outcomes": [ "Conceção da API GraphQL estruturada", "Tipos definidos e suas relações", "Limpar consultas, mutações e subscrições" ], "steps": [ "Que problemas estão os utilizadores de API a tentar resolver? De que dados necessitam?", "Definir tipos GraphQL e seus atributos: Quais são os principais tipos expostos (por exemplo, utilizador, encomenda, produto)?", "Mapear relações entre tipos: Como é que os tipos se relacionam uns com os outros em consultas aninhadas?", "Especificar consultas para a recuperação de dados", "Definir mutações para a modificação de dados: Que operações irão modificar os dados (por exemplo, criar, atualizar, eliminar)?", "Assinaturas de esboços para actualizações em tempo real", "Definir autenticação e autorização: Quem pode aceder a que campos ou tipos?", "Considerar se existem restrições de paginação, filtragem ou limitação de taxa" ], "canvasId": "graphqlCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-design-principles", "slug": "resources/api-design-principles", "title": "Princípios de conceção da API", "description": "Um guia conciso sobre usabilidade, descobribilidade e consistência da API, baseado em regras de design partilhadas e nas necessidades reais dos utilizadores.", "category": "guideline", "icon": "edit-document-outline", "order": 14, "outcomes": [ "Melhor compreensão dos princípios de conceção das API", "Abordagem normalizada utilizando os princípios de conceção da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "**Conceção que coloca o utilizador em primeiro lugar:** iniciar cada ciclo de APIOps recolhendo os objetivos do utilizador e os termos do domínio para que as APIs resolvam problemas reais.", "**Nomeação e comportamento consistentes:** aplicar convenções partilhadas para recursos, erros e formatos para tornar as APIs previsíveis.", "**Orientado para contratos:** capturar a interface com OpenAPI ou AsyncAPI antes da codificação para alinhar as equipas e permitir a automatização.", "**Usabilidade e facilidade de descoberta:** fornecer documentação e exemplos claros para que os programadores compreendam rapidamente como utilizar a API.", "**Iterar com segurança:** desenvolver os projetos em pequenos incrementos, com versões, para que as alterações não perturbem os utilizadores existentes." ], "canvasId": null, "sourcePath": "src/snippets/api-style-guide.json", "sourceUrl": null, "contentMarkdown": "{\r\n \"guidelines\": [\r\n {\r\n \"id\": \"REST-CONTRACT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST implement endpoints, parameters, request bodies, response bodies, and error responses as defined in the validated OpenAPI contract.\",\r\n \"relatedAuditItems\": [\r\n \"spec-contains-schemas\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CONTRACT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST keep the implementation, published OpenAPI description, gateway configuration, and developer portal documentation aligned on every change.\",\r\n \"relatedAuditItems\": [\r\n \"docs-auto-generated\",\r\n \"spec-auto-updated\",\r\n \"spec-validated-on-change\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VALIDATION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate path parameters, query parameters, headers, and JSON request bodies against the OpenAPI schema before business processing.\",\r\n \"relatedAuditItems\": [\r\n \"mandatory-fields-specified\",\r\n \"400-errors-specific\",\r\n \"inputs-auto-validated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST expose business-oriented resources and attributes rather than raw backend tables, internal service payloads, or system-specific field names.\",\r\n \"relatedAuditItems\": [\r\n \"hides-raw-backend-data\",\r\n \"design-consistent\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST preserve validated meanings of entities, attributes, statuses, and source-of-truth rules across all endpoints and operations.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\",\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use descriptive English names for resources and attributes.\",\r\n \"relatedAuditItems\": [\r\n \"descriptive-english-naming\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST avoid unexplained acronyms in public field and resource names.\",\r\n \"relatedAuditItems\": [\r\n \"field-names-avoid-acronyms\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use ISO date-time values with timezone information where dates are exposed.\",\r\n \"relatedAuditItems\": [\r\n \"dates-use-iso\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API SHOULD use standard codes, controlled vocabularies, and standardized value sets where applicable.\",\r\n \"relatedAuditItems\": [\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST describe the business value and feature intent of each endpoint or capability.\",\r\n \"relatedAuditItems\": [\r\n \"endpoint-descriptions-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST include examples for endpoints, request bodies, response bodies, and key attributes.\",\r\n \"relatedAuditItems\": [\r\n \"examples-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API SHOULD use consistent pagination, filtering, sorting, and response conventions across resources.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-GET-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use GET for safe read-only operations and MUST NOT define a request body for GET operations.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-POST-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use POST for resource creation and other non-idempotent operations.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-PUT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use PUT only for full resource replacement.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-DELETE-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use DELETE to remove resources.\",\r\n \"relatedAuditItems\": [\r\n \"delete-for-remove\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PATH-01\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"resource-modeling\",\r\n \"requirement\": \"The REST API SHOULD keep endpoint paths shallow and avoid more than two resource or sub-resource levels unless explicitly justified.\",\r\n \"relatedAuditItems\": [\r\n \"paths-max-two-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-200-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 200 OK for successful reads and updates that include a response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"post-returns-200\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-201-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 201 Created and the created resource identifier when a new resource is created.\",\r\n \"relatedAuditItems\": [\r\n \"create-returns-identifiers\",\r\n \"post-returns-201\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 204 No Content for successful delete operations that do not return a body.\",\r\n \"relatedAuditItems\": [\r\n \"delete-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API SHOULD return 204 No Content for successful operations that intentionally return no response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-empty-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-400-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST define 400 Bad Request responses with specific and actionable validation error information.\",\r\n \"relatedAuditItems\": [\r\n \"400-errors-specific\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-401-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 401 Unauthorized for missing or invalid credentials.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-403-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 403 Forbidden for authenticated clients lacking sufficient permission.\",\r\n \"relatedAuditItems\": [\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VERSION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"versioning\",\r\n \"requirement\": \"The REST API MUST define a versioning strategy before production release, and the strategy MUST be supportable by the API gateway.\",\r\n \"relatedAuditItems\": [\r\n \"versioning-decided\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST require authentication for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use token-based authentication or another approved modern authentication mechanism for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"token-auth\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-03\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST enforce object-level and function-level authorization on every protected operation.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\",\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST mitigate OWASP API risks including broken object level authorization, broken function level authorization, injection, and unrestricted resource consumption.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"rate-limits-enforced\",\r\n \"no-sensitive-data-in-urls\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-05\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use HTTPS or another approved encrypted protocol for all traffic.\",\r\n \"relatedAuditItems\": [\r\n \"uses-https\",\r\n \"encryption-in-transit\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-06\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST NOT expose sensitive information in URLs, query strings, logs, or unnecessary response fields.\",\r\n \"relatedAuditItems\": [\r\n \"no-sensitive-data-in-urls\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-07\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API SHOULD use UUIDs or other non-sequential public identifiers where direct database identifiers would increase exposure risk.\",\r\n \"relatedAuditItems\": [\r\n \"pseudo-identifiers\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-08\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST implement CSRF protection where relevant to the authentication model and client interaction pattern.\",\r\n \"relatedAuditItems\": [\r\n \"csrf-protection\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST define and enforce rate limits, throttling, or quotas according to capacity expectations.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST implement resilience controls such as timeouts, fallback behavior, and degradation handling according to business impact.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\",\r\n \"encryption-in-transit\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-OBS-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"observability\",\r\n \"requirement\": \"The REST API MUST implement logs, metrics, and monitoring needed to observe validation failures, auth failures, traffic, latency, and dependency health.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published through an API management platform.\",\r\n \"relatedAuditItems\": [\r\n \"published-via-api-management\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be accessible only through approved API gateway paths and managed entry points.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API SHOULD be visible in a developer portal with documentation generated from the contract.\",\r\n \"relatedAuditItems\": [\r\n \"visible-in-dev-portal\",\r\n \"docs-auto-generated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published under an approved organizational domain.\",\r\n \"relatedAuditItems\": [\r\n \"official-domain\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate the specification, schema, and examples on every change.\",\r\n \"relatedAuditItems\": [\r\n \"spec-validated-on-change\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST pass concept, design, security, and production-readiness checks before release.\",\r\n \"relatedAuditItems\": [\r\n \"concept-items-audited\",\r\n \"design-items-audited\"\r\n ]\r\n }\r\n ]\r\n}", "draft": false }, { "id": "contract-first-design", "slug": "resources/contract-first-design", "title": "Primeira conceção do contrato", "description": "Uma diretriz que defende abordagens API-first utilizando contratos formais (por exemplo, OpenAPI) para alinhar as partes interessadas antes do desenvolvimento.", "category": "guideline", "icon": "edit-document-outline", "order": 146, "outcomes": [ "Melhor compreensão dos princípios de conceção da primeira fase do contrato", "Abordagem normalizada utilizando a conceção orientada por contrato", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar." ], "canvasId": null, "sourcePath": "src/snippets/api-contract-example.yaml", "sourceUrl": null, "contentMarkdown": "openapi: 3.0.3\r\ninfo:\r\n title: Sample Catalog API\r\n version: 1.0.0\r\n description: |\r\n Starter example for a read-only APIOps Cycles API.\r\n This example keeps the contract audit-friendly and easy to extend.\r\nservers:\r\n - url: /v1\r\n description: Versioned API base path\r\ntags:\r\n - name: catalog\r\n description: Browse and search catalog items\r\npaths:\r\n /items:\r\n get:\r\n tags: [catalog]\r\n summary: List catalog items\r\n description: Returns a paginated list of public catalog items.\r\n operationId: listItems\r\n parameters:\r\n - $ref: \"#/components/parameters/searchTerm\"\r\n - $ref: \"#/components/parameters/categoryId\"\r\n - $ref: \"#/components/parameters/page\"\r\n - $ref: \"#/components/parameters/pageSize\"\r\n responses:\r\n \"200\":\r\n description: Item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n examples:\r\n default:\r\n value:\r\n data:\r\n - itemId: item-123\r\n slug: blue-widget\r\n name: Blue Widget\r\n status: published\r\n page:\r\n number: 1\r\n size: 20\r\n totalItems: 1\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"429\":\r\n $ref: \"#/components/responses/TooManyRequests\"\r\n /items/{itemId}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by id\r\n description: Returns a single public catalog item by opaque identifier.\r\n operationId: getItemById\r\n parameters:\r\n - $ref: \"#/components/parameters/itemId\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /items/by-slug/{slug}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by slug\r\n description: Returns a single item by public slug.\r\n operationId: getItemBySlug\r\n parameters:\r\n - $ref: \"#/components/parameters/slug\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /categories/{categoryId}/items:\r\n get:\r\n tags: [catalog]\r\n summary: List items in category\r\n description: Returns public items in a category.\r\n operationId: listItemsByCategory\r\n parameters:\r\n - $ref: \"#/components/parameters/categoryId\"\r\n responses:\r\n \"200\":\r\n description: Category item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\ncomponents:\r\n parameters:\r\n itemId:\r\n name: itemId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: item-123\r\n slug:\r\n name: slug\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9]+(?:-[a-z0-9]+)*$\"\r\n example: blue-widget\r\n categoryId:\r\n name: categoryId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: home-goods\r\n searchTerm:\r\n name: searchTerm\r\n in: query\r\n required: false\r\n schema:\r\n type: string\r\n minLength: 1\r\n example: widget\r\n page:\r\n name: page\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n default: 1\r\n pageSize:\r\n name: pageSize\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n maximum: 100\r\n default: 20\r\n responses:\r\n BadRequest:\r\n description: Validation failed\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n examples:\r\n default:\r\n value:\r\n code: BAD_REQUEST\r\n message: Invalid request\r\n NotFound:\r\n description: Resource not found\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n TooManyRequests:\r\n description: Rate limit exceeded\r\n headers:\r\n Retry-After:\r\n schema:\r\n type: integer\r\n description: Seconds until the next allowed request.\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n schemas:\r\n ItemListResponse:\r\n type: object\r\n required: [data, page]\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/ItemSummary\"\r\n page:\r\n $ref: \"#/components/schemas/Page\"\r\n ItemSummary:\r\n type: object\r\n required: [itemId, slug, name, status]\r\n properties:\r\n itemId:\r\n type: string\r\n slug:\r\n type: string\r\n name:\r\n type: string\r\n status:\r\n type: string\r\n enum: [published, hidden]\r\n ItemDetail:\r\n allOf:\r\n - $ref: \"#/components/schemas/ItemSummary\"\r\n - type: object\r\n properties:\r\n description:\r\n type: string\r\n categories:\r\n type: array\r\n items:\r\n type: string\r\n variants:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/Variant\"\r\n Variant:\r\n type: object\r\n required: [variantId, sku, price, inventory]\r\n properties:\r\n variantId:\r\n type: string\r\n sku:\r\n type: string\r\n price:\r\n $ref: \"#/components/schemas/Price\"\r\n inventory:\r\n $ref: \"#/components/schemas/Inventory\"\r\n Price:\r\n type: object\r\n required: [amount, currency]\r\n properties:\r\n amount:\r\n type: number\r\n format: decimal\r\n currency:\r\n type: string\r\n example: EUR\r\n Inventory:\r\n type: object\r\n required: [available]\r\n properties:\r\n available:\r\n type: integer\r\n minimum: 0\r\n reserved:\r\n type: integer\r\n minimum: 0\r\n source:\r\n type: string\r\n Page:\r\n type: object\r\n required: [number, size, totalItems]\r\n properties:\r\n number:\r\n type: integer\r\n size:\r\n type: integer\r\n totalItems:\r\n type: integer\r\n ErrorResponse:\r\n type: object\r\n required: [code, message]\r\n properties:\r\n code:\r\n type: string\r\n message:\r\n type: string\r\n", "draft": true } ], "evidence": [ "spec", "contract", "design-artifact", "documentation" ] }, { "index": 5, "id": "api-delivery", "slug": "method/api-delivery", "icon": "code", "title": "Entrega da API", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia.", "whyItMatters": "Mesmo os melhores conceções de API falham se a entrega for inconsistente. Esta estação assegura que as suas APIs são construídas com qualidade, testadas exaustivamente e implementadas de forma fiável - permitindo iterações mais rápidas e maior confiança.", "applyInWork": "Fornecer estruturas de codificação, bibliotecas e normas para a implementação de API. Implementar pipelines de CI/CD, estruturas de garantia de qualidade e ferramentas de automatização da disponibilização.", "outcomes": [ "APIs implementadas utilizando estruturas e padrões testados", "Pipelines de CI/CD fiáveis e automatizados", "Testes funcionais e não funcionais integrados", "Condutas de entrega seguras e conformes" ], "steps": [ { "text": "Utilize as Melhores Práticas de Desenvolvimento de API como orientação para implementar o contrato validado com frameworks e bibliotecas estabelecidos, garantindo que o resultado seja reutilizável e sustentável.", "resourceId": "api-development-best-practices", "resourceTitle": "Boas práticas de desenvolvimento de API", "canvasId": null }, { "text": "Construa a implementação da API a partir do contrato validado usando frameworks, bibliotecas e padrões da equipa estabelecidos.", "resourceId": "api-development-best-practices", "resourceTitle": "Boas práticas de desenvolvimento de API", "canvasId": null }, { "text": "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "resourceId": "api-testing-best-practices", "resourceTitle": "Boas práticas de teste de API", "canvasId": null }, { "text": "Utilize pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null }, { "text": "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "resourceId": "api-security-best-practices", "resourceTitle": "Boas práticas de segurança da API", "canvasId": null }, { "text": "Utilize a lista de verificação de auditoria da API para garantir que a API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "questions": [ "Utilize as Melhores Práticas de Desenvolvimento de API como orientação para implementar o contrato validado com frameworks e bibliotecas estabelecidos, garantindo que o resultado seja reutilizável e sustentável.", "Construa a implementação da API a partir do contrato validado usando frameworks, bibliotecas e padrões da equipa estabelecidos.", "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Utilize pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "Utilize a lista de verificação de auditoria da API para garantir que a API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Fornecer estruturas de codificação, bibliotecas e normas para a implementação de API. Implementar pipelines de CI/CD, estruturas de garantia de qualidade e ferramentas de automatização da disponibilização.", "Mesmo os melhores conceções de API falham se a entrega for inconsistente. Esta estação assegura que as suas APIs são construídas com qualidade, testadas exaustivamente e implementadas de forma fiável - permitindo iterações mais rápidas e maior confiança." ], "criteria": [ "architecture-patterns-validated", "hide-backend-discrepancies", "design-reflects-business-value", "api-consistency" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." } ], "baseTitle": "Entrega da API - Fornecer APIs seguras e fiáveis", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "delivery", "stakeholders": [ { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "lead", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "core", "responsibilities": [] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "api-development-best-practices", "slug": "resources/api-development-best-practices", "title": "Boas práticas de desenvolvimento de API", "description": "Orientações de implementação para transformar um contrato de interface da API validado numa base de código de API consistente e sustentável, utilizando bibliotecas padrão, padrões reutilizáveis e fluxos de trabalho de desenvolvimento alinhados.", "category": "guideline", "icon": "edit-document-outline", "order": 112, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de desenvolvimento de API", "Abordagem normalizada utilizando as boas práticas de desenvolvimento de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplique essas práticas ao contrato de interface da API validado e ao plano de implementação antes do início da codificação.", "Utilize frameworks, bibliotecas e padrões de codificação estabelecidos para implementar o contrato de forma consistente e sustentável." ], "canvasId": null, "sourcePath": "src/snippets/pt/api-design-principles-guidance.md", "sourceUrl": null, "contentMarkdown": "## Como iniciar o trabalho de entrega da API com base nas fases anteriores (“etapas”)\r\nUtilize estas orientações no início da `API Delivery` (entrega da API), após a revisão e aceitação do contrato da API (por exemplo, OpenAPI) e dos principais resultados das etapas anteriores.\r\nO objetivo não é desenvolver a implementação de forma isolada. O objetivo é transformar os resultados acordados nas etapas anteriores em uma estrutura de código concreta, regras de validação, comportamento em tempo de execução e decisões relativas à entrega do produto API.\r\n\r\n---\r\n\r\n### 1. Comece a partir do contrato validado\r\n- Trate o contrato de API validado como o principal ponto de referência para as decisões de implementação.\r\n- Mantenha o contrato e a implementação alinhados ao longo de toda a entrega do produto API.\r\n- Use o contrato para orientar a validação de solicitações, o mapeamento de respostas, a documentação e os testes.\r\n\r\n---\r\n\r\n### 2. Use os resultados do domínio para preservar o significado comercial\r\n- Use os resultados do `Domain Canvas` para orientar a nomenclatura, como a implementação é dividida em responsabilidades comerciais claras e como diferentes sistemas de back-end são conectados sem expor suas diferenças.\r\n- Preserve os significados validados de entidades, atributos, status e regras de fonte de verdade.\r\n- Evite vazar modelos específicos do back-end ou inconsistências para a API pública.\r\n\r\n---\r\n\r\n### 3. Use os resultados da jornada para preservar fluxos críticos\r\n- Use os resultados do `Customer Journey Canvas` para identificar quais fluxos de usuários são mais importantes para serem atendidos primeiro.\r\n- Use os resultados da `API Consumer Experience` para manter a API compreensível, previsível e fácil de integrar.\r\n- Deixe que as prioridades de jornada acordadas decidam quais caminhos de implementação precisam da maior confiabilidade, menor latência, erros mais claros e maior foco operacional.\r\n\r\n---\r\n\r\n### 4. Use os resultados da Proposta de Valor para preservar o valor para o consumidor\r\n- Use os resultados do `API Value Proposition Canvas` para manter a implementação focada nas dores, ganhos e recursos da API acordados.\r\n- Preserve os significados dos campos, o comportamento e as promessas que tornaram a API valiosa nas etapas anteriores.\r\n- Garanta que o tratamento de erros, a atualização e a nomenclatura apoiem tanto a experiência do desenvolvedor pretendida quanto o caso de uso de negócios.\r\n\r\n---\r\n\r\n### 5. Use os resultados da arquitetura para moldar as decisões de tempo de execução\r\n- Use os resultados do `Business Impact Canvas` para orientar as decisões sobre resiliência, tempo limite, fallback e degradação.\r\n- Use os resultados do `Locations Canvas` para orientar os limites de rede, limites de confiança, caminhos de acesso e restrições de implantação.\r\n- Use os resultados do `Capacity Canvas` para orientar limites de taxa, cache, escalonamento e comportamento em picos de carga.\r\n- Use as orientações do `API Metrics And Analytics` para decidir o que deve ser observado desde a primeira implementação em diante.\r\n\r\n---\r\n\r\n### 6. Use os resultados do projeto de interação e protocolo para moldar a estrutura do código\r\n- Use os resultados do `Interaction Canvas` para evitar implementar estilos de interação não suportados prematuramente.\r\n- Use os resultados do projeto `REST`, `Event` ou `GraphQL` para moldar o comportamento de solicitação, resposta e validação específico do protocolo.\r\n- Reflete o estilo de interação selecionado claramente na estrutura do código, nas responsabilidades e na estratégia de testes.\r\n\r\n---\r\n\r\n### 7. Usa os resultados da auditoria para melhorar a entrega antes que a codificação avance demais\r\n- Usa as conclusões da auditoria para remover ambiguidades antes que a implementação se espalhe pela base de código.\r\n- Corrige regras de solicitação pouco claras, validações ausentes, contratos de erro fracos e lacunas operacionais logo no início.\r\n- Trate a auditoria como um ciclo de melhoria de projeto antes da produção, não apenas como uma etapa de decisão final.\r\n\r\n---\r\n\r\n### 8. Aplique as orientações e, em seguida, resuma\r\n- Aplique estas orientações à API atual e ao plano de implementação.\r\n- Resuma as implicações para a estrutura do código, validação de solicitações, integração de fontes, segurança, monitoramento e alertas, e testes.\r\n- Não crie um artefato de entrega separado, a menos que a equipe ou o usuário precise especificamente de um.\r\n", "draft": true }, { "id": "api-testing-best-practices", "slug": "resources/api-testing-best-practices", "title": "Boas práticas de teste de API", "description": "Diretrizes para a implementação de testes automatizados funcionais, de desempenho e de segurança ao longo do ciclo de vida da API.", "category": "guideline", "icon": "edit-document-outline", "order": 133, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de teste de API", "Abordagem normalizada utilizando as boas práticas de teste de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Integrar testes funcionais e não funcionais no pipeline CI/CD para garantir que as APIs cumprems normas de qualidade.", "Utilizar ferramentas de teste automatizadas para validar a funcionalidade, a segurança e o desempenho da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "apiops-CI-CD-for-apis", "slug": "resources/apiops-CI-CD-for-apis", "title": "APIOps CI/CD para APIs", "description": "Orientação de disponibilização que integra tarefas do ciclo de vida da API - design, teste, governação - em pipelines de integração e entrega contínuas.", "category": "guideline", "icon": "edit-document-outline", "order": 140, "outcomes": [ "Melhor compreensão dos princípios de CI/CD para APIs", "Abordagem normalizada utilizando CI/CD para APIs", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilizar pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-security-best-practices", "slug": "resources/api-security-best-practices", "title": "Boas práticas de segurança da API", "description": "Um conjunto de controlos acionáveis para proteger APIs, incluindo autenticação, autorização, encriptação, limitação de taxas e verificações de conformidade ao nível do pipeline.", "category": "guideline", "icon": "edit-document-outline", "order": 130, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de segurança da API", "Abordagem normalizada utilizando as boas práticas de segurança da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "Implemente medidas de segurança como autenticação, autorização, encriptação e limitação de taxas para proteger as APIs de ameaças.", "Implementar verificações de segurança automatizadas e validações de conformidade no pipeline CI/CD para garantir que as APIs são seguras e compatíveis." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "implementation", "pipeline-config", "test-report", "security-report" ] }, { "index": 6, "id": "api-audit", "slug": "method/api-audit", "icon": "check-box-outline", "title": "Auditoria da API", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição.", "whyItMatters": "As APIs são produtos de longa duração e devem atender às expectativas de qualidade, consistência e conformidade. A auditoria conecta as decisões de conceção, a implementação e a prontidão operacional a padrões definidos, reduzindo o risco antes da exposição.", "applyInWork": "Estabeleça um processo de auditoria consistente que avalie a prontidão da API em todas as etapas do ciclo de vida usando critérios, evidências e padrões definidos. Garanta que as lacunas sejam identificadas antecipadamente e resolvidas antes da publicação.", "outcomes": [ "As APIs cumprems normas internas e externas", "Documentação clara das decisões de conceção e implementação da API", "Segurança, desempenho e conformidade validados", "Redução do risco de problemas na produção" ], "steps": [ { "text": "Realizar auditorias para garantir que as APIs cumprems normas organizacionais, técnicas e legais antes da publicação.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null }, { "text": "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas.", "resourceId": "api-compliance-best-practices", "resourceTitle": "Boas práticas de conformidade da API", "canvasId": null }, { "text": "Colaborar com as equipas de governação e especialistas no domínio para garantir que as APIs estão prontas para produção.", "resourceTitle": "", "canvasId": null } ], "questions": [ "Realizar auditorias para garantir que as APIs cumprems normas organizacionais, técnicas e legais antes da publicação.", "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas.", "Colaborar com as equipas de governação e especialistas no domínio para garantir que as APIs estão prontas para produção.", "Estabeleça um processo de auditoria consistente que avalie a prontidão da API em todas as etapas do ciclo de vida usando critérios, evidências e padrões definidos. Garanta que as lacunas sejam identificadas antecipadamente e resolvidas antes da publicação.", "As APIs são produtos de longa duração e devem atender às expectativas de qualidade, consistência e conformidade. A auditoria conecta as decisões de conceção, a implementação e a prontidão operacional a padrões definidos, reduzindo o risco antes da exposição." ], "criteria": [ "architecture-patterns-validated", "design-reflects-business-value", "api-description-available", "api-consistency", "api-contract-tested" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-description-available", "title": "A interface e as suas capacidades estão documentadas de forma suficientemente clara para revisão, auditoria e onboarding.", "description": "The API and its exposed capabilities are described clearly enough for review, audit, and onboarding." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." }, { "id": "api-contract-tested", "title": "O contrato de interface foi validado e testado face aos requisitos funcionais e não funcionais.", "description": "The API contract is tested and meets functional and non-functional requirements." } ], "baseTitle": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "publishing", "stakeholders": [ { "id": "governance-specialist", "sourceKey": "governance-specialist", "sourceStakeholderId": "governance-specialist", "title": "Responsável pela governação API", "description": "Representa práticas de revisão, auditoria e governação em toda a organização para qualidade e conformidade das APIs.", "involvement": "lead", "responsibilities": [] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "core", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "core", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "consulted", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "api-audit-checklist", "slug": "resources/api-audit-checklist", "title": "Lista de verificação de auditoria da API", "description": "Uma lista de verificação baseada no ciclo de vida para verificar a prontidão da API em design, entrega, publicação e conformidade utilizando critérios de auditoria e evidências definidos.", "category": "checklist", "icon": "check-box-outline", "order": 13, "outcomes": [ "Melhor compreensão dos princípios da lista de controlo de auditoria da API", "Abordagem normalizada utilizando a lista de verificação de auditoria da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilize a lista de verificação de auditoria da API para garantir que a conceção da API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Realize auditorias para avaliar a cobertura do ciclo de vida e verificar se a API satisfaz os padrões de negócio, conceção e operacionais.", "Certifique-se de que a documentação, os modelos de segurança, a configuração do gateway e os requisitos legais estejam claramente definidos, validados e comprovados por evidências." ], "canvasId": null, "sourcePath": "src/snippets/api-audit-checklist.json", "sourceUrl": null, "contentMarkdown": "{\r\n \"profiles\": {\r\n \"read-only\": {\r\n \"description\": \"API profile that is read-only and does not allow create, update, or delete operations.\"\r\n },\r\n \"full-crud\": {\r\n \"description\": \"General API profile that allows create, update, and delete operations.\"\r\n }\r\n },\r\n \"lifecycleStages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6\r\n }\r\n ],\r\n \"stages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1,\r\n \"items\": [\r\n {\r\n \"id\": \"based-on-clear-business-needs\",\r\n \"label\": \"API is based on clear business needs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiBusinessModelCanvas\",\r\n \"apiValuePropositionCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"design-artifact\",\r\n \"documentation\",\r\n \"research\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\",\r\n \"specs/canvases/api-product-strategy/apiBusinessModelCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"concept-items-audited\",\r\n \"label\": \"All concept checklist items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"strategy\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\",\r\n \"api-opportunity-documented\",\r\n \"api-reusability\",\r\n \"value-prop-validated\",\r\n \"consumer-segments-identified\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/concept-review-report.json\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2,\r\n \"items\": [\r\n {\r\n \"id\": \"versioning-decided\",\r\n \"label\": \"Versioning strategy decided and supported by gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VERSION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-versioning-best-practices\",\r\n \"apiops-CI-CD-for-apis\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"ci-cd\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"only-via-gateway\",\r\n \"label\": \"Only accessible via API gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-02\",\r\n \"REST-CAPACITY-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"businessImpactCanvas\",\r\n \"locationsCanvas\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"infra-config\",\r\n \"security-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"rate-limits-enforced\",\r\n \"label\": \"Rate limits are enforced\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CAPACITY-01\",\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"capacityCanvas\",\r\n \"api-security-best-practices\",\r\n \"scalable-infrastructure-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"runtime\",\r\n \"monitoring\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-platform-architecture/capacityCanvas.empty.json\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3,\r\n \"items\": [\r\n {\r\n \"id\": \"endpoint-descriptions-present\",\r\n \"label\": \"Endpoints have business value and feature descriptions\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"operationDescriptions\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\",\r\n \"api-opportunity-documented\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiValuePropositionCanvas\",\r\n \"customerJourneyCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"hides-raw-backend-data\",\r\n \"label\": \"API hides raw backend data and is designed for shared use\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"interactionCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/domainCanvas.empty.json\",\r\n \"specs/canvases/api-design/interactionCanvas.empty.json\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"design-consistent\",\r\n \"label\": \"API design is consistent with other APIs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-02\",\r\n \"REST-CX-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-design/restCanvas.empty.json\",\r\n \"docs/api/design/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"descriptive-english-naming\",\r\n \"label\": \"Data and attribute naming uses descriptive English\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"fieldNamesDescriptive\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"mandatory-fields-specified\",\r\n \"label\": \"Mandatory fields are specified\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"requiredFieldsPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"dates-use-iso\",\r\n \"label\": \"Dates use ISO format with timezone\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"dateFormatTimezone\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"general-data-uses-standard-values\",\r\n \"label\": \"General data uses standard values\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"standardizedEnumsOrPatterns\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"field-names-avoid-acronyms\",\r\n \"label\": \"Field names avoid acronyms and use full words\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"avoidAcronyms\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"create-returns-identifiers\",\r\n \"label\": \"Creating new resources returns identifiers\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is read-only and does not create resources.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"paths-max-two-resources\",\r\n \"label\": \"Endpoint paths contain max two resources or sub-resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"pathDepthMax\",\r\n \"maxDepth\": 2\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PATH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"examples-present\",\r\n \"label\": \"Endpoints and attributes include examples\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-for-create-update\",\r\n \"label\": \"POST is used for create or update\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose create or update operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-for-remove\",\r\n \"label\": \"DELETE is used to remove resources\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose delete operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-no-request-body\",\r\n \"label\": \"GET has no request body and returns content\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"getNoRequestBody\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-empty-returns-204\",\r\n \"label\": \"GET returns 204 if response body is empty\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current contract returns content for all GET operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-200\",\r\n \"label\": \"POST returns 200 OK when updating\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST updates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-201\",\r\n \"label\": \"POST returns 201 Created with ID on create\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST creates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-returns-204\",\r\n \"label\": \"DELETE returns 204 on success\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose DELETE operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"400-errors-specific\",\r\n \"label\": \"400 errors provide specific error information\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"errorResponsesSpecific\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-400-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"api-audit-checklist\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"401-unauthorized\",\r\n \"label\": \"401 Unauthorized for wrong credentials\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current public storefront contract is intentionally unauthenticated.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-401-01\",\r\n \"REST-SEC-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"403-forbidden\",\r\n \"label\": \"403 Forbidden for unauthorized operations\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current profile is public read-only and exposes no unauthorized operations.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-403-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-contains-schemas\",\r\n \"label\": \"Spec contains request and response schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"schemasPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"restCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"pseudo-identifiers\",\r\n \"label\": \"UUIDs or pseudo-identifiers instead of DB IDs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"opaqueIdentifiers\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-07\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"no-sensitive-data-in-urls\",\r\n \"label\": \"No sensitive data in URLs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"noSensitiveDataInPaths\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-06\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"http-methods-match-resources\",\r\n \"label\": \"HTTP methods only for intended resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"methodResourceConsistency\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\",\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4,\r\n \"items\": [\r\n {\r\n \"id\": \"design-items-audited\",\r\n \"label\": \"All prototype and design items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"design\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"design-reflects-business-value\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/production-readiness-review.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-validated-on-change\",\r\n \"label\": \"Spec validated on every change\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"validationWorkflowPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\",\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"schema-and-examples-pass\",\r\n \"label\": \"Schema and examples pass validation\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPassValidation\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-contract-tested\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\",\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"api-audit-checklist\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"uses-https\",\r\n \"label\": \"Uses HTTPS or encrypted protocols\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"auth-protection\",\r\n \"label\": \"Endpoints protected by authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"token-auth\",\r\n \"label\": \"Token-based authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"csrf-protection\",\r\n \"label\": \"Protected against CSRF\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-08\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-development-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"inputs-auto-validated\",\r\n \"label\": \"Inputs auto-validated by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"contract-first-design\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\",\r\n \"test\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"outputs-auto-escaped\",\r\n \"label\": \"Outputs auto-escaped by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"JSON APIs do not typically require output escaping in the same way as HTML rendering.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"encryption-in-transit\",\r\n \"label\": \"Encryption for data in transit and storage\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"infra-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"message-integrity\",\r\n \"label\": \"Message integrity implemented\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"monitoring\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5,\r\n \"items\": [\r\n {\r\n \"id\": \"published-via-api-management\",\r\n \"label\": \"Published via API management\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"ci-cd\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"visible-in-dev-portal\",\r\n \"label\": \"Visible in developer portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-community-engagement-strategies\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"docs-auto-generated\",\r\n \"label\": \"Docs auto-generated from spec and schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\",\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"documentation\",\r\n \"ci-cd\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/publishing/README.md\",\r\n \"docs/api/audit/design-audit.read-only.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-auto-updated\",\r\n \"label\": \"Spec auto-updated to gateway and dev portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"contract-first-design\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"gateway-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"official-domain\",\r\n \"label\": \"Published under official organization domain\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6,\r\n \"items\": []\r\n }\r\n ],\r\n \"guidelines\": [\r\n {\r\n \"id\": \"REST-CONTRACT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST implement endpoints, parameters, request bodies, response bodies, and error responses as defined in the validated OpenAPI contract.\",\r\n \"relatedAuditItems\": [\r\n \"spec-contains-schemas\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CONTRACT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST keep the implementation, published OpenAPI description, gateway configuration, and developer portal documentation aligned on every change.\",\r\n \"relatedAuditItems\": [\r\n \"docs-auto-generated\",\r\n \"spec-auto-updated\",\r\n \"spec-validated-on-change\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VALIDATION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate path parameters, query parameters, headers, and JSON request bodies against the OpenAPI schema before business processing.\",\r\n \"relatedAuditItems\": [\r\n \"mandatory-fields-specified\",\r\n \"400-errors-specific\",\r\n \"inputs-auto-validated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST expose business-oriented resources and attributes rather than raw backend tables, internal service payloads, or system-specific field names.\",\r\n \"relatedAuditItems\": [\r\n \"based-on-clear-business-needs\",\r\n \"hides-raw-backend-data\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST preserve validated meanings of entities, attributes, statuses, and source-of-truth rules across all endpoints and operations.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\",\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use descriptive English names for resources and attributes.\",\r\n \"relatedAuditItems\": [\r\n \"descriptive-english-naming\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST avoid unexplained acronyms in public field and resource names.\",\r\n \"relatedAuditItems\": [\r\n \"field-names-avoid-acronyms\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use ISO date-time values with timezone information where dates are exposed.\",\r\n \"relatedAuditItems\": [\r\n \"dates-use-iso\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API SHOULD use standard codes, controlled vocabularies, and standardized value sets where applicable.\",\r\n \"relatedAuditItems\": [\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST describe the business value and feature intent of each endpoint or capability.\",\r\n \"relatedAuditItems\": [\r\n \"endpoint-descriptions-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST include examples for endpoints, request bodies, response bodies, and key attributes.\",\r\n \"relatedAuditItems\": [\r\n \"examples-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API SHOULD use consistent pagination, filtering, sorting, and response conventions across resources.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-GET-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use GET for safe read-only operations and MUST NOT define a request body for GET operations.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-POST-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use POST for resource creation and other non-idempotent operations.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-PUT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use PUT only for full resource replacement.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-DELETE-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use DELETE to remove resources.\",\r\n \"relatedAuditItems\": [\r\n \"delete-for-remove\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PATH-01\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"resource-modeling\",\r\n \"requirement\": \"The REST API SHOULD keep endpoint paths shallow and avoid more than two resource or sub-resource levels unless explicitly justified.\",\r\n \"relatedAuditItems\": [\r\n \"paths-max-two-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-200-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 200 OK for successful reads and updates that include a response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"post-returns-200\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-201-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 201 Created and the created resource identifier when a new resource is created.\",\r\n \"relatedAuditItems\": [\r\n \"create-returns-identifiers\",\r\n \"post-returns-201\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 204 No Content for successful delete operations that do not return a body.\",\r\n \"relatedAuditItems\": [\r\n \"delete-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API SHOULD return 204 No Content for successful operations that intentionally return no response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-empty-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-400-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST define 400 Bad Request responses with specific and actionable validation error information.\",\r\n \"relatedAuditItems\": [\r\n \"400-errors-specific\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-401-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 401 Unauthorized for missing or invalid credentials.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-403-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 403 Forbidden for authenticated clients lacking sufficient permission.\",\r\n \"relatedAuditItems\": [\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VERSION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"versioning\",\r\n \"requirement\": \"The REST API MUST define a versioning strategy before production release, and the strategy MUST be supportable by the API gateway.\",\r\n \"relatedAuditItems\": [\r\n \"versioning-decided\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST require authentication for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use token-based authentication or another approved modern authentication mechanism for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"token-auth\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-03\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST enforce object-level and function-level authorization on every protected operation.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\",\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST mitigate OWASP API risks including broken object level authorization, broken function level authorization, injection, and unrestricted resource consumption.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"rate-limits-enforced\",\r\n \"no-sensitive-data-in-urls\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-05\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use HTTPS or another approved encrypted protocol for all traffic.\",\r\n \"relatedAuditItems\": [\r\n \"uses-https\",\r\n \"encryption-in-transit\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-06\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST NOT expose sensitive information in URLs, query strings, logs, or unnecessary response fields.\",\r\n \"relatedAuditItems\": [\r\n \"no-sensitive-data-in-urls\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-07\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API SHOULD use UUIDs or other non-sequential public identifiers where direct database identifiers would increase exposure risk.\",\r\n \"relatedAuditItems\": [\r\n \"pseudo-identifiers\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-08\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST implement CSRF protection where relevant to the authentication model and client interaction pattern.\",\r\n \"relatedAuditItems\": [\r\n \"csrf-protection\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST define and enforce rate limits, throttling, or quotas according to capacity expectations.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST implement resilience controls such as timeouts, fallback behavior, and degradation handling according to business impact.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-OBS-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"observability\",\r\n \"requirement\": \"The REST API MUST implement logs, metrics, and monitoring needed to observe validation failures, auth failures, traffic, latency, and dependency health.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published through an API management platform.\",\r\n \"relatedAuditItems\": [\r\n \"published-via-api-management\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be accessible only through approved API gateway paths and managed entry points.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API SHOULD be visible in a developer portal with documentation generated from the contract.\",\r\n \"relatedAuditItems\": [\r\n \"visible-in-dev-portal\",\r\n \"docs-auto-generated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published under an approved organizational domain.\",\r\n \"relatedAuditItems\": [\r\n \"official-domain\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate the specification, schema, and examples on every change.\",\r\n \"relatedAuditItems\": [\r\n \"spec-validated-on-change\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST pass concept, design, security, and production-readiness checks before release.\",\r\n \"relatedAuditItems\": [\r\n \"concept-items-audited\",\r\n \"design-items-audited\"\r\n ]\r\n }\r\n ]\r\n}\r\n", "draft": false }, { "id": "api-compliance-best-practices", "slug": "resources/api-compliance-best-practices", "title": "Boas práticas de conformidade da API", "description": "Garantir que as APIs cumprem conformidade legal, regulamentar e interna através de documentação, controlos e validações automatizadas.", "category": "guideline", "icon": "edit-document-outline", "order": 104, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de conformidade da API", "Abordagem normalizada utilizando as Melhores Práticas de Conformidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Documentar as medidas de conformidade e garantir que são comunicadas às partes interessadas e aos utilizadores.", "Implementar medidas para garantir que as APIs cumprem estes requisitos, incluindo encriptação de dados, controlos de acesso e pistas de auditoria.", "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "audit-report", "compliance-report", "security-report", "test-report" ] }, { "index": 7, "id": "api-publishing", "slug": "method/api-publishing", "icon": "deployed-code-outline", "title": "Publicação da API", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos.", "whyItMatters": "A publicação é mais do que a disponibilização - trata-se de capacidade de descoberta, acesso e suporte. Se as APIs não forem publicadas corretamente, não serão utilizadas, reutilizadas ou protegidas de forma eficaz.", "applyInWork": "Permitir que as APIs sejam publicadas no ambiente relevante e ter mecanismos claros de registo e acesso (por exemplo, chaves de API, OAuth, planos de subscrição), dependendo dos segmentos de consumidores de API e dos requisitos de segurança e conformidade.", "outcomes": [ "APIs publicadas no ambiente correto (privado, parceiro, público)", "Processos claros de integração e registo da API", "Documentação, modelos e políticas de segurança disponíveis", "APIs prontas para escala e governação" ], "steps": [ { "text": "Publicar APIs nos gateways e ambientes adequados para apoiar a reutilização por vários consumidores de API.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null }, { "text": "Documentar a forma como os consumidores encontram e utilizam a API, incluindo processos de integração e registo.", "resourceId": "api-onboarding-best-practices", "resourceTitle": "Boas práticas de integração de API", "canvasId": null }, { "text": "Garantir que os modelos de segurança, a configuração da porta de ligação e os termos legais sejam claros e acessíveis aos consumidores.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "questions": [ "Publicar APIs nos gateways e ambientes adequados para apoiar a reutilização por vários consumidores de API.", "Documentar a forma como os consumidores encontram e utilizam a API, incluindo processos de integração e registo.", "Garantir que os modelos de segurança, a configuração da porta de ligação e os termos legais sejam claros e acessíveis aos consumidores.", "Permitir que as APIs sejam publicadas no ambiente relevante e ter mecanismos claros de registo e acesso (por exemplo, chaves de API, OAuth, planos de subscrição), dependendo dos segmentos de consumidores de API e dos requisitos de segurança e conformidade.", "A publicação é mais do que a disponibilização - trata-se de capacidade de descoberta, acesso e suporte. Se as APIs não forem publicadas corretamente, não serão utilizadas, reutilizadas ou protegidas de forma eficaz." ], "criteria": [ "audit-passed", "audit-reports-shared", "api-ready-for-publishing", "api-documentation-ready" ], "criteriaDetails": [ { "id": "audit-passed", "title": "A solução passa as verificações de qualidade, segurança, conformidade e prontidão.", "description": "The API passes compliance, security, and audit checks." }, { "id": "audit-reports-shared", "title": "As conclusões da auditoria e as decisões de correção são partilhadas com as partes interessadas relevantes.", "description": "Audit findings and remediation decisions are shared with the relevant stakeholders." }, { "id": "api-ready-for-publishing", "title": "A capacidade está pronta para ser publicada ou disponibilizada através do mecanismo de entrega selecionado.", "description": "The API is ready to be deployed and exposed through the intended gateways and environments." }, { "id": "api-documentation-ready", "title": "A documentação orientada para os utilizadores e os materiais de onboarding estão prontos.", "description": "Consumer-facing API documentation is complete enough for publishing and onboarding." } ], "baseTitle": "Publicação de API - Publique APIs com confiança", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "publishing", "stakeholders": [ { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "lead", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "apiops-CI-CD-for-apis", "slug": "resources/apiops-CI-CD-for-apis", "title": "APIOps CI/CD para APIs", "description": "Orientação de disponibilização que integra tarefas do ciclo de vida da API - design, teste, governação - em pipelines de integração e entrega contínuas.", "category": "guideline", "icon": "edit-document-outline", "order": 140, "outcomes": [ "Melhor compreensão dos princípios de CI/CD para APIs", "Abordagem normalizada utilizando CI/CD para APIs", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilizar pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-audit-checklist", "slug": "resources/api-audit-checklist", "title": "Lista de verificação de auditoria da API", "description": "Uma lista de verificação baseada no ciclo de vida para verificar a prontidão da API em design, entrega, publicação e conformidade utilizando critérios de auditoria e evidências definidos.", "category": "checklist", "icon": "check-box-outline", "order": 13, "outcomes": [ "Melhor compreensão dos princípios da lista de controlo de auditoria da API", "Abordagem normalizada utilizando a lista de verificação de auditoria da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilize a lista de verificação de auditoria da API para garantir que a conceção da API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Realize auditorias para avaliar a cobertura do ciclo de vida e verificar se a API satisfaz os padrões de negócio, conceção e operacionais.", "Certifique-se de que a documentação, os modelos de segurança, a configuração do gateway e os requisitos legais estejam claramente definidos, validados e comprovados por evidências." ], "canvasId": null, "sourcePath": "src/snippets/api-audit-checklist.json", "sourceUrl": null, "contentMarkdown": "{\r\n \"profiles\": {\r\n \"read-only\": {\r\n \"description\": \"API profile that is read-only and does not allow create, update, or delete operations.\"\r\n },\r\n \"full-crud\": {\r\n \"description\": \"General API profile that allows create, update, and delete operations.\"\r\n }\r\n },\r\n \"lifecycleStages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6\r\n }\r\n ],\r\n \"stages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1,\r\n \"items\": [\r\n {\r\n \"id\": \"based-on-clear-business-needs\",\r\n \"label\": \"API is based on clear business needs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiBusinessModelCanvas\",\r\n \"apiValuePropositionCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"design-artifact\",\r\n \"documentation\",\r\n \"research\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\",\r\n \"specs/canvases/api-product-strategy/apiBusinessModelCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"concept-items-audited\",\r\n \"label\": \"All concept checklist items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"strategy\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\",\r\n \"api-opportunity-documented\",\r\n \"api-reusability\",\r\n \"value-prop-validated\",\r\n \"consumer-segments-identified\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/concept-review-report.json\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2,\r\n \"items\": [\r\n {\r\n \"id\": \"versioning-decided\",\r\n \"label\": \"Versioning strategy decided and supported by gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VERSION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-versioning-best-practices\",\r\n \"apiops-CI-CD-for-apis\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"ci-cd\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"only-via-gateway\",\r\n \"label\": \"Only accessible via API gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-02\",\r\n \"REST-CAPACITY-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"businessImpactCanvas\",\r\n \"locationsCanvas\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"infra-config\",\r\n \"security-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"rate-limits-enforced\",\r\n \"label\": \"Rate limits are enforced\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CAPACITY-01\",\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"capacityCanvas\",\r\n \"api-security-best-practices\",\r\n \"scalable-infrastructure-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"runtime\",\r\n \"monitoring\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-platform-architecture/capacityCanvas.empty.json\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3,\r\n \"items\": [\r\n {\r\n \"id\": \"endpoint-descriptions-present\",\r\n \"label\": \"Endpoints have business value and feature descriptions\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"operationDescriptions\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\",\r\n \"api-opportunity-documented\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiValuePropositionCanvas\",\r\n \"customerJourneyCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"hides-raw-backend-data\",\r\n \"label\": \"API hides raw backend data and is designed for shared use\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"interactionCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/domainCanvas.empty.json\",\r\n \"specs/canvases/api-design/interactionCanvas.empty.json\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"design-consistent\",\r\n \"label\": \"API design is consistent with other APIs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-02\",\r\n \"REST-CX-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-design/restCanvas.empty.json\",\r\n \"docs/api/design/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"descriptive-english-naming\",\r\n \"label\": \"Data and attribute naming uses descriptive English\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"fieldNamesDescriptive\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"mandatory-fields-specified\",\r\n \"label\": \"Mandatory fields are specified\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"requiredFieldsPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"dates-use-iso\",\r\n \"label\": \"Dates use ISO format with timezone\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"dateFormatTimezone\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"general-data-uses-standard-values\",\r\n \"label\": \"General data uses standard values\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"standardizedEnumsOrPatterns\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"field-names-avoid-acronyms\",\r\n \"label\": \"Field names avoid acronyms and use full words\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"avoidAcronyms\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"create-returns-identifiers\",\r\n \"label\": \"Creating new resources returns identifiers\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is read-only and does not create resources.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"paths-max-two-resources\",\r\n \"label\": \"Endpoint paths contain max two resources or sub-resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"pathDepthMax\",\r\n \"maxDepth\": 2\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PATH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"examples-present\",\r\n \"label\": \"Endpoints and attributes include examples\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-for-create-update\",\r\n \"label\": \"POST is used for create or update\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose create or update operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-for-remove\",\r\n \"label\": \"DELETE is used to remove resources\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose delete operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-no-request-body\",\r\n \"label\": \"GET has no request body and returns content\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"getNoRequestBody\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-empty-returns-204\",\r\n \"label\": \"GET returns 204 if response body is empty\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current contract returns content for all GET operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-200\",\r\n \"label\": \"POST returns 200 OK when updating\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST updates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-201\",\r\n \"label\": \"POST returns 201 Created with ID on create\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST creates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-returns-204\",\r\n \"label\": \"DELETE returns 204 on success\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose DELETE operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"400-errors-specific\",\r\n \"label\": \"400 errors provide specific error information\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"errorResponsesSpecific\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-400-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"api-audit-checklist\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"401-unauthorized\",\r\n \"label\": \"401 Unauthorized for wrong credentials\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current public storefront contract is intentionally unauthenticated.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-401-01\",\r\n \"REST-SEC-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"403-forbidden\",\r\n \"label\": \"403 Forbidden for unauthorized operations\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current profile is public read-only and exposes no unauthorized operations.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-403-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-contains-schemas\",\r\n \"label\": \"Spec contains request and response schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"schemasPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"restCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"pseudo-identifiers\",\r\n \"label\": \"UUIDs or pseudo-identifiers instead of DB IDs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"opaqueIdentifiers\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-07\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"no-sensitive-data-in-urls\",\r\n \"label\": \"No sensitive data in URLs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"noSensitiveDataInPaths\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-06\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"http-methods-match-resources\",\r\n \"label\": \"HTTP methods only for intended resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"methodResourceConsistency\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\",\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4,\r\n \"items\": [\r\n {\r\n \"id\": \"design-items-audited\",\r\n \"label\": \"All prototype and design items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"design\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"design-reflects-business-value\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/production-readiness-review.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-validated-on-change\",\r\n \"label\": \"Spec validated on every change\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"validationWorkflowPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\",\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"schema-and-examples-pass\",\r\n \"label\": \"Schema and examples pass validation\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPassValidation\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-contract-tested\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\",\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"api-audit-checklist\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"uses-https\",\r\n \"label\": \"Uses HTTPS or encrypted protocols\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"auth-protection\",\r\n \"label\": \"Endpoints protected by authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"token-auth\",\r\n \"label\": \"Token-based authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"csrf-protection\",\r\n \"label\": \"Protected against CSRF\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-08\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-development-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"inputs-auto-validated\",\r\n \"label\": \"Inputs auto-validated by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"contract-first-design\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\",\r\n \"test\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"outputs-auto-escaped\",\r\n \"label\": \"Outputs auto-escaped by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"JSON APIs do not typically require output escaping in the same way as HTML rendering.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"encryption-in-transit\",\r\n \"label\": \"Encryption for data in transit and storage\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"infra-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"message-integrity\",\r\n \"label\": \"Message integrity implemented\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"monitoring\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5,\r\n \"items\": [\r\n {\r\n \"id\": \"published-via-api-management\",\r\n \"label\": \"Published via API management\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"ci-cd\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"visible-in-dev-portal\",\r\n \"label\": \"Visible in developer portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-community-engagement-strategies\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"docs-auto-generated\",\r\n \"label\": \"Docs auto-generated from spec and schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\",\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"documentation\",\r\n \"ci-cd\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/publishing/README.md\",\r\n \"docs/api/audit/design-audit.read-only.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-auto-updated\",\r\n \"label\": \"Spec auto-updated to gateway and dev portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"contract-first-design\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"gateway-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"official-domain\",\r\n \"label\": \"Published under official organization domain\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6,\r\n \"items\": []\r\n }\r\n ],\r\n \"guidelines\": [\r\n {\r\n \"id\": \"REST-CONTRACT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST implement endpoints, parameters, request bodies, response bodies, and error responses as defined in the validated OpenAPI contract.\",\r\n \"relatedAuditItems\": [\r\n \"spec-contains-schemas\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CONTRACT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST keep the implementation, published OpenAPI description, gateway configuration, and developer portal documentation aligned on every change.\",\r\n \"relatedAuditItems\": [\r\n \"docs-auto-generated\",\r\n \"spec-auto-updated\",\r\n \"spec-validated-on-change\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VALIDATION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate path parameters, query parameters, headers, and JSON request bodies against the OpenAPI schema before business processing.\",\r\n \"relatedAuditItems\": [\r\n \"mandatory-fields-specified\",\r\n \"400-errors-specific\",\r\n \"inputs-auto-validated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST expose business-oriented resources and attributes rather than raw backend tables, internal service payloads, or system-specific field names.\",\r\n \"relatedAuditItems\": [\r\n \"based-on-clear-business-needs\",\r\n \"hides-raw-backend-data\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST preserve validated meanings of entities, attributes, statuses, and source-of-truth rules across all endpoints and operations.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\",\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use descriptive English names for resources and attributes.\",\r\n \"relatedAuditItems\": [\r\n \"descriptive-english-naming\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST avoid unexplained acronyms in public field and resource names.\",\r\n \"relatedAuditItems\": [\r\n \"field-names-avoid-acronyms\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use ISO date-time values with timezone information where dates are exposed.\",\r\n \"relatedAuditItems\": [\r\n \"dates-use-iso\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API SHOULD use standard codes, controlled vocabularies, and standardized value sets where applicable.\",\r\n \"relatedAuditItems\": [\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST describe the business value and feature intent of each endpoint or capability.\",\r\n \"relatedAuditItems\": [\r\n \"endpoint-descriptions-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST include examples for endpoints, request bodies, response bodies, and key attributes.\",\r\n \"relatedAuditItems\": [\r\n \"examples-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API SHOULD use consistent pagination, filtering, sorting, and response conventions across resources.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-GET-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use GET for safe read-only operations and MUST NOT define a request body for GET operations.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-POST-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use POST for resource creation and other non-idempotent operations.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-PUT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use PUT only for full resource replacement.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-DELETE-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use DELETE to remove resources.\",\r\n \"relatedAuditItems\": [\r\n \"delete-for-remove\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PATH-01\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"resource-modeling\",\r\n \"requirement\": \"The REST API SHOULD keep endpoint paths shallow and avoid more than two resource or sub-resource levels unless explicitly justified.\",\r\n \"relatedAuditItems\": [\r\n \"paths-max-two-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-200-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 200 OK for successful reads and updates that include a response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"post-returns-200\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-201-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 201 Created and the created resource identifier when a new resource is created.\",\r\n \"relatedAuditItems\": [\r\n \"create-returns-identifiers\",\r\n \"post-returns-201\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 204 No Content for successful delete operations that do not return a body.\",\r\n \"relatedAuditItems\": [\r\n \"delete-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API SHOULD return 204 No Content for successful operations that intentionally return no response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-empty-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-400-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST define 400 Bad Request responses with specific and actionable validation error information.\",\r\n \"relatedAuditItems\": [\r\n \"400-errors-specific\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-401-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 401 Unauthorized for missing or invalid credentials.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-403-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 403 Forbidden for authenticated clients lacking sufficient permission.\",\r\n \"relatedAuditItems\": [\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VERSION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"versioning\",\r\n \"requirement\": \"The REST API MUST define a versioning strategy before production release, and the strategy MUST be supportable by the API gateway.\",\r\n \"relatedAuditItems\": [\r\n \"versioning-decided\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST require authentication for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use token-based authentication or another approved modern authentication mechanism for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"token-auth\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-03\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST enforce object-level and function-level authorization on every protected operation.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\",\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST mitigate OWASP API risks including broken object level authorization, broken function level authorization, injection, and unrestricted resource consumption.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"rate-limits-enforced\",\r\n \"no-sensitive-data-in-urls\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-05\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use HTTPS or another approved encrypted protocol for all traffic.\",\r\n \"relatedAuditItems\": [\r\n \"uses-https\",\r\n \"encryption-in-transit\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-06\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST NOT expose sensitive information in URLs, query strings, logs, or unnecessary response fields.\",\r\n \"relatedAuditItems\": [\r\n \"no-sensitive-data-in-urls\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-07\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API SHOULD use UUIDs or other non-sequential public identifiers where direct database identifiers would increase exposure risk.\",\r\n \"relatedAuditItems\": [\r\n \"pseudo-identifiers\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-08\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST implement CSRF protection where relevant to the authentication model and client interaction pattern.\",\r\n \"relatedAuditItems\": [\r\n \"csrf-protection\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST define and enforce rate limits, throttling, or quotas according to capacity expectations.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST implement resilience controls such as timeouts, fallback behavior, and degradation handling according to business impact.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-OBS-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"observability\",\r\n \"requirement\": \"The REST API MUST implement logs, metrics, and monitoring needed to observe validation failures, auth failures, traffic, latency, and dependency health.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published through an API management platform.\",\r\n \"relatedAuditItems\": [\r\n \"published-via-api-management\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be accessible only through approved API gateway paths and managed entry points.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API SHOULD be visible in a developer portal with documentation generated from the contract.\",\r\n \"relatedAuditItems\": [\r\n \"visible-in-dev-portal\",\r\n \"docs-auto-generated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published under an approved organizational domain.\",\r\n \"relatedAuditItems\": [\r\n \"official-domain\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate the specification, schema, and examples on every change.\",\r\n \"relatedAuditItems\": [\r\n \"spec-validated-on-change\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST pass concept, design, security, and production-readiness checks before release.\",\r\n \"relatedAuditItems\": [\r\n \"concept-items-audited\",\r\n \"design-items-audited\"\r\n ]\r\n }\r\n ]\r\n}\r\n", "draft": false } ], "evidence": [ "gateway-config", "developer-portal", "documentation", "release-record" ] }, { "index": 8, "id": "monitoring-and-improving", "slug": "method/monitoring-and-improving", "icon": "analytics-outline", "title": "Monitorizacao e melhoria da API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua.", "whyItMatters": "A entrega da API não pára no lançamento. Sem monitorização, as equipas não podem melhorar a adoção, o desempenho ou o ROI. Esta estação garante que as APIs permaneçam úteis, seguras e evoluindo com as necessidades do negócio.", "applyInWork": "Criar quadros analíticos para acompanhar o desempenho e o envolvimento. Desenvolver ciclos de feedback, ferramentas de análise e estratégias de envolvimento para APIs.", "outcomes": [ "Métricas de desempenho e utilização definidas e controladas", "Ciclos de feedback do programador em vigor", "Questões identificadas e tratadas continuamente", "Iteração da API alinhada com as necessidades dos utilizadores" ], "steps": [ { "text": "Monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "resourceId": "api-metrics-and-analytics", "resourceTitle": "Métricas e análise de API", "canvasId": null }, { "text": "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API.", "resourceId": "api-community-engagement-strategies", "resourceTitle": "Estratégias de envolvimento da comunidade API", "canvasId": null }, { "text": "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null } ], "questions": [ "Monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua.", "Criar quadros analíticos para acompanhar o desempenho e o envolvimento. Desenvolver ciclos de feedback, ferramentas de análise e estratégias de envolvimento para APIs.", "A entrega da API não pára no lançamento. Sem monitorização, as equipas não podem melhorar a adoção, o desempenho ou o ROI. Esta estação garante que as APIs permaneçam úteis, seguras e evoluindo com as necessidades do negócio." ], "criteria": [ "api-documentation-ready", "consumer-support-ready", "legal-compliance-clear" ], "criteriaDetails": [ { "id": "api-documentation-ready", "title": "A documentação orientada para os utilizadores e os materiais de onboarding estão prontos.", "description": "Consumer-facing API documentation is complete enough for publishing and onboarding." }, { "id": "consumer-support-ready", "title": "Os processos de onboarding, suporte e comunicação para utilizadores estão prontos.", "description": "Registration, support, and communication processes are ready for API consumers." }, { "id": "legal-compliance-clear", "title": "Os requisitos legais, de privacidade e de conformidade para publicação ou disponibilização estão definidos e compreendidos.", "description": "Legal, privacy, and compliance requirements for publishing are defined and understood." } ], "baseTitle": "Monitorização e melhoria - para valor API", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "improving", "stakeholders": [ { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "lead", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "core", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "consulted", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "api-metrics-and-analytics", "slug": "resources/api-metrics-and-analytics", "title": "Métricas e análise de API", "description": "Um recurso para definir, recolher e analisar o desempenho da API e os dados de utilização para alinhar os KPIs técnicos com os resultados de negócio.", "category": "guideline", "icon": "edit-document-outline", "order": 119, "outcomes": [ "Melhor compreensão dos princípios de métrica e análise de API", "Abordagem normalizada utilizando métricas e análise de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação" ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-community-engagement-strategies", "slug": "resources/api-community-engagement-strategies", "title": "Estratégias de envolvimento da comunidade API", "description": "Um manual para promover a adoção de APIs, cultivando comunidades através de conteúdos, canais de apoio, ciclos de feedback e estratégias de envolvimento social.", "category": "guideline", "icon": "edit-document-outline", "order": 103, "outcomes": [ "Melhor compreensão dos princípios das estratégias de envolvimento da comunidade da API", "Abordagem normalizada utilizando as estratégias de envolvimento da comunidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Desenvolver estratégias de marketing para promover as APIs junto de públicos-alvo, incluindo redes sociais, blogues e webinars.", "Criar materiais promocionais (por exemplo, estudos de casos, histórias de sucesso) que realcem o valor e as vantagens das APIs.", "Criar materiais educativos (por exemplo, tutoriais, documentação) que expliquem as características, as vantagens e os padrões de utilização da API.", "Interagir com os utilizadores da API através de ciclos de feedback, canais de apoio e fóruns da comunidade para compreender as suas necessidades e melhorar a adoção da API.", "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "metrics", "consumer-feedback", "incident-report", "roadmap" ] } ] }, { "id": "integration-productization-cycle", "slug": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao.", "purpose": "Orientar a concecao de capacidades de integracao reutilizaveis antes de escolher um estilo de implementacao API, evento, ficheiro, stream, produto de dados, integracao direta ou hibrido.", "audiences": [], "audienceStakeholders": [ { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "lead", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [ { "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "role": "suggested-answer-owner" } ] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [ { "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "role": "suggested-answer-owner" } ] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "core", "responsibilities": [ { "resourceId": "capabilityValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da Capacidade", "canvasId": "capabilityValuePropositionCanvas", "role": "suggested-answer-owner" }, { "resourceId": "capabilityBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da Capacidade", "canvasId": "capabilityBusinessModelCanvas", "role": "suggested-answer-owner" } ] }, { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "core", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "lead", "responsibilities": [ { "resourceId": "consumerExperienceRequirementsCanvas", "resourceTitle": "Canvas de Requisitos da Experiência do Utilizador", "canvasId": "consumerExperienceRequirementsCanvas", "role": "suggested-answer-owner" } ] }, { "id": "customer-specialist", "sourceKey": "customer-specialist", "sourceStakeholderId": "customer-specialist", "title": "Representante de cliente ou parceiro", "description": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "lead", "responsibilities": [ { "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "role": "suggested-answer-owner" } ] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "core", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "lead", "responsibilities": [] }, { "id": "governance-specialist", "sourceKey": "governance-specialist", "sourceStakeholderId": "governance-specialist", "title": "Responsável pela governação API", "description": "Representa práticas de revisão, auditoria e governação em toda a organização para qualidade e conformidade das APIs.", "involvement": "lead", "responsibilities": [] }, { "id": "partner-specialist", "sourceKey": "partner-specialist", "sourceStakeholderId": "partner-specialist", "title": "Gestor de parceiros ou fornecedores", "description": "Coordena relações com parceiros, fornecedores ou prestadores externos que influenciam a estratégia e entrega da capacidade ou API.", "involvement": "core", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "core", "responsibilities": [] } ], "entryCriteria": [ "business-goals-defined", "api-opportunity-documented" ], "exitCriteria": [ "architecture-patterns-validated", "api-description-available", "audit-passed" ], "entryCriteriaDetails": [ { "id": "business-goals-defined", "title": "Os objetivos de negócio estão definidos.", "description": "Business goals are defined." }, { "id": "api-opportunity-documented", "title": "A oportunidade de capacidade está identificada e documentada.", "description": "Individual API opportunities are identified and documented." } ], "exitCriteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "api-description-available", "title": "A interface e as suas capacidades estão documentadas de forma suficientemente clara para revisão, auditoria e onboarding.", "description": "The API and its exposed capabilities are described clearly enough for review, audit, and onboarding." }, { "id": "audit-passed", "title": "A solução passa as verificações de qualidade, segurança, conformidade e prontidão.", "description": "The API passes compliance, security, and audit checks." } ], "questionnaireResources": [ { "stationId": "api-product-strategy", "stationTitle": "Estratégia da capacidade de integração", "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "suggestedAnswerOwner": { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [ { "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-product-strategy", "stationTitle": "Estratégia da capacidade de integração", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "suggestedAnswerOwner": { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [ { "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-product-strategy", "stationTitle": "Estratégia da capacidade de integração", "resourceId": "capabilityValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da Capacidade", "canvasId": "capabilityValuePropositionCanvas", "suggestedAnswerOwner": { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "core", "responsibilities": [ { "resourceId": "capabilityValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da Capacidade", "canvasId": "capabilityValuePropositionCanvas", "role": "suggested-answer-owner" }, { "resourceId": "capabilityBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da Capacidade", "canvasId": "capabilityBusinessModelCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-product-strategy", "stationTitle": "Estratégia da capacidade de integração", "resourceId": "capabilityBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da Capacidade", "canvasId": "capabilityBusinessModelCanvas", "suggestedAnswerOwner": { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "core", "responsibilities": [ { "resourceId": "capabilityValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da Capacidade", "canvasId": "capabilityValuePropositionCanvas", "role": "suggested-answer-owner" }, { "resourceId": "capabilityBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da Capacidade", "canvasId": "capabilityBusinessModelCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-consumer-experience", "stationTitle": "Requisitos e integração de consumidores da integração", "resourceId": "consumerExperienceRequirementsCanvas", "resourceTitle": "Canvas de Requisitos da Experiência do Utilizador", "canvasId": "consumerExperienceRequirementsCanvas", "suggestedAnswerOwner": { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "lead", "responsibilities": [ { "resourceId": "consumerExperienceRequirementsCanvas", "resourceTitle": "Canvas de Requisitos da Experiência do Utilizador", "canvasId": "consumerExperienceRequirementsCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-platform-architecture", "stationTitle": "Arquitetura de integracao e decisoes de plataforma", "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "suggestedAnswerOwner": { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "lead", "responsibilities": [ { "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-platform-architecture", "stationTitle": "Arquitetura de integracao e decisoes de plataforma", "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas", "suggestedAnswerOwner": { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "core", "responsibilities": [ { "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-platform-architecture", "stationTitle": "Arquitetura de integracao e decisoes de plataforma", "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas", "suggestedAnswerOwner": { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "core", "responsibilities": [ { "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas", "role": "suggested-answer-owner" } ] } } ], "stations": [ { "index": 1, "id": "api-product-strategy", "slug": "method/api-product-strategy", "icon": "strategy-outline", "title": "Estratégia da capacidade de integração", "description": "Enquadrar a capacidade de integracao reutilizavel, a necessidade de negocio, o ownership e a reutilizacao esperada antes de selecionar o estilo de implementacao.", "whyItMatters": "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais.", "applyInWork": "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "outcomes": [ "Uma proposta de valor e um público-alvo da API simples", "Linguagem partilhada entre o produto, a conceção e a tecnologia", "Um argumento sólido ou um caso para financiamento/aprovação" ], "steps": [ { "text": "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas" }, { "text": "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas" }, { "text": "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas" }, { "text": "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "resourceId": "apiBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da API", "canvasId": "apiBusinessModelCanvas" } ], "questions": [ "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais." ], "criteria": [ "metrics-feedback-available", "business-goals-defined", "market-research-done", "stakeholder-approval" ], "criteriaDetails": [ { "id": "metrics-feedback-available", "title": "Sinais de mercado relevantes, feedback ou conhecimento operacional estão disponíveis para orientar esta oportunidade de capacidade.", "description": "Relevant market signals, feedback, or operational insights are available to guide this API opportunity." }, { "id": "business-goals-defined", "title": "Os objetivos de negócio estão definidos.", "description": "Business goals are defined." }, { "id": "market-research-done", "title": "A investigação de mercado identifica oportunidades de capacidade.", "description": "Market research identifies API opportunities." }, { "id": "stakeholder-approval", "title": "As partes interessadas relevantes concordam que vale a pena explorar e priorizar esta oportunidade de capacidade.", "description": "Relevant stakeholders agree this API opportunity is worth exploring and prioritizing." } ], "baseTitle": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "strategy", "stakeholders": [ { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "lead", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [ { "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "role": "suggested-answer-owner" } ] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [ { "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "role": "suggested-answer-owner" } ] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "core", "responsibilities": [ { "resourceId": "capabilityValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da Capacidade", "canvasId": "capabilityValuePropositionCanvas", "role": "suggested-answer-owner" }, { "resourceId": "capabilityBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da Capacidade", "canvasId": "capabilityBusinessModelCanvas", "role": "suggested-answer-owner" } ] }, { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "core", "responsibilities": [] }, { "id": "partner-specialist", "sourceKey": "partner-specialist", "sourceStakeholderId": "partner-specialist", "title": "Gestor de parceiros ou fornecedores", "description": "Coordena relações com parceiros, fornecedores ou prestadores externos que influenciam a estratégia e entrega da capacidade ou API.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityBusinessModelCanvas", "slug": "resources/capability-business-model-canvas", "title": "Canvas do Modelo de Negócio da Capacidade", "description": "Um canvas de modelo de negócio para capacidades de integração reutilizáveis, cobrindo valor, utilizadores, propriedade, envolvimento, custos e benefícios sem assumir disponibilização por API.", "category": "canvas", "icon": "dashboard-outline", "order": 3.1, "outcomes": [ "Modelo operacional viável para a capacidade reutilizável", "Propriedade, utilizadores, canais, parceiros e necessidades de suporte clarificados", "Custos e benefícios visíveis antes do compromisso com a arquitetura" ], "steps": [ "Resuma a proposta de valor da capacidade.", "Identifique segmentos de utilizadores e canais de envolvimento.", "Defina atividades, recursos e parceiros-chave.", "Capte custos e benefícios.", "Clarifique propriedade, financiamento, suporte e expectativas de ciclo de vida.", "Valide o modelo com utilizadores, produtores e partes interessadas de governação." ], "canvasId": "capabilityBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false } ], "evidence": [ "design-artifact", "documentation", "research", "roadmap" ] }, { "index": 2, "id": "api-consumer-experience", "slug": "method/api-consumer-experience", "icon": "deployed-code-account-outline", "title": "Requisitos e integração de consumidores da integração", "description": "Recolha consumidores da integração, responsabilidades dos fornecedores, necessidades de integração, expectativas de serviço e restrições operacionais.", "whyItMatters": "As APIs excelentes não funcionam apenas - elas são intuitivas. Quer o consumidor seja um programador interno, um parceiro externo ou um agente de IA, a sua experiência determina a adoção.\n\nSnum plano de experiência claro:\n- Grandes APIs ficam sem uso\n- As equipas perdem tempo a tentar adivinhar como utilizar a sua API\n- Os ciclos de feedback estão quebrados ou ausentes.\n\nEsta estação ajuda-o a ver a sua API através dos olhos dos seus consumidores.", "applyInWork": "Fornecer diretrizes, ferramentas e mecanismos de feedback para compreender, analisar e melhorar a experiência interna e externa dos programadores e parceiros.", "outcomes": [ "Identifique e dê prioridade aos seus consumidores de API", "Definir o percurso da experiência API", "Planeamento da integração, documentação e feedback", "Melhorar a adoção através de empatia genuína + Experiência do Programador (DX)" ], "steps": [ { "text": "Analise o Canvas da Proposta de Valor da API existente sob a perspectiva do consumidor da API. Mantenha as tarefas de negócios suportadas estáveis ​​e enriqueça os recursos que aliviam problemas e possibilitam ganhos com as preocupações do consumidor da API, para que elas possam orientar as decisões de conceção futuras.", "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas" }, { "text": "Utilize o Canvas do Percurso do Cliente para a jornada do consumidor da API, desde a descoberta e avaliação até a integração, resolução de problemas e uso contínuo.", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas" }, { "text": "Utilize a jornada resultante para melhorar a integração, a documentação, o suporte e os ciclos de feedback para o consumidor da API.", "resourceId": "api-onboarding-best-practices", "resourceTitle": "Boas práticas de integração de API", "canvasId": null } ], "questions": [ "Analise o Canvas da Proposta de Valor da API existente sob a perspectiva do consumidor da API. Mantenha as tarefas de negócios suportadas estáveis ​​e enriqueça os recursos que aliviam problemas e possibilitam ganhos com as preocupações do consumidor da API, para que elas possam orientar as decisões de conceção futuras.", "Utilize o Canvas do Percurso do Cliente para a jornada do consumidor da API, desde a descoberta e avaliação até a integração, resolução de problemas e uso contínuo.", "Utilize a jornada resultante para melhorar a integração, a documentação, o suporte e os ciclos de feedback para o consumidor da API.", "Fornecer diretrizes, ferramentas e mecanismos de feedback para compreender, analisar e melhorar a experiência interna e externa dos programadores e parceiros.", "As APIs excelentes não funcionam apenas - elas são intuitivas. Quer o consumidor seja um programador interno, um parceiro externo ou um agente de IA, a sua experiência determina a adoção.\n\nSnum plano de experiência claro:\n- Grandes APIs ficam sem uso\n- As equipas perdem tempo a tentar adivinhar como utilizar a sua API\n- Os ciclos de feedback estão quebrados ou ausentes.\n\nEsta estação ajuda-o a ver a sua API através dos olhos dos seus consumidores." ], "criteria": [ "api-opportunity-documented", "api-reusability", "hide-backend-discrepancies", "value-prop-validated", "consumer-segments-identified", "api-roadmap-defined" ], "criteriaDetails": [ { "id": "api-opportunity-documented", "title": "A oportunidade de capacidade está identificada e documentada.", "description": "Individual API opportunities are identified and documented." }, { "id": "api-reusability", "title": "A capacidade responde a uma necessidade clara de negócio e é reutilizável pelos utilizadores previstos.", "description": "The API meets a clear business need and is reusable for multiple API consumers." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "value-prop-validated", "title": "A proposta de valor da capacidade foi validada com partes interessadas de negócio e utilizadores.", "description": "The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders." }, { "id": "consumer-segments-identified", "title": "Os segmentos de utilizadores estão identificados.", "description": "API consumer segments (internal and external) are identified." }, { "id": "api-roadmap-defined", "title": "Está definido um roadmap de implementação de alto nível.", "description": "High-level roadmaps for API development are established." } ], "baseTitle": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "strategy", "stakeholders": [ { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "lead", "responsibilities": [ { "resourceId": "consumerExperienceRequirementsCanvas", "resourceTitle": "Canvas de Requisitos da Experiência do Utilizador", "canvasId": "consumerExperienceRequirementsCanvas", "role": "suggested-answer-owner" } ] }, { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "core", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [] }, { "id": "customer-specialist", "sourceKey": "customer-specialist", "sourceStakeholderId": "customer-specialist", "title": "Representante de cliente ou parceiro", "description": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "involvement": "core", "responsibilities": [] }, { "id": "partner-specialist", "sourceKey": "partner-specialist", "sourceStakeholderId": "partner-specialist", "title": "Gestor de parceiros ou fornecedores", "description": "Coordena relações com parceiros, fornecedores ou prestadores externos que influenciam a estratégia e entrega da capacidade ou API.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "consulted", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "design-artifact", "documentation", "consumer-feedback" ] }, { "index": 3, "id": "api-platform-architecture", "slug": "method/api-platform-architecture", "icon": "code-blocks-outline", "title": "Arquitetura de integracao e decisoes de plataforma", "description": "Selecionar a arquitetura de integracao, o estilo de implementacao e as capacidades de plataforma, tendo em conta as restricoes e o modelo de governacao.", "whyItMatters": "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência.", "applyInWork": "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "outcomes": [ "Corte APIs redundantes e reduza os custos da plataforma de nuvem", "Implementar uma governação consistente snum forte controlo do topo para a base", "Conceção para reutilização interna e escalabilidade externa" ], "steps": [ { "text": "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas" }, { "text": "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas" }, { "text": "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas" }, { "text": "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "resourceId": "api-metrics-and-analytics", "resourceTitle": "Métricas e análise de API", "canvasId": null } ], "questions": [ "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência." ], "criteria": [ "api-reusability", "hide-backend-discrepancies", "value-prop-validated", "consumer-segments-identified", "api-roadmap-defined" ], "criteriaDetails": [ { "id": "api-reusability", "title": "A capacidade responde a uma necessidade clara de negócio e é reutilizável pelos utilizadores previstos.", "description": "The API meets a clear business need and is reusable for multiple API consumers." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "value-prop-validated", "title": "A proposta de valor da capacidade foi validada com partes interessadas de negócio e utilizadores.", "description": "The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders." }, { "id": "consumer-segments-identified", "title": "Os segmentos de utilizadores estão identificados.", "description": "API consumer segments (internal and external) are identified." }, { "id": "api-roadmap-defined", "title": "Está definido um roadmap de implementação de alto nível.", "description": "High-level roadmaps for API development are established." } ], "baseTitle": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "architecture", "stakeholders": [ { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "lead", "responsibilities": [ { "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "role": "suggested-answer-owner" } ] }, { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "core", "responsibilities": [ { "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas", "role": "suggested-answer-owner" } ] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "core", "responsibilities": [ { "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas", "role": "suggested-answer-owner" } ] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "api-architect", "sourceKey": "api-architect", "sourceStakeholderId": "api-architect", "title": "Arquiteto API", "description": "Responsável pela arquitetura API, pelos princípios de desenho e pela qualidade dos contratos de interface.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "partner-integration-guidelines", "slug": "resources/partner-integration-guidelines", "title": "Diretrizes de integração de parceiros", "description": "Listas de verificação de integração e padrões de comunicação para gerir os aspectos técnicos e legais das relações com APIs de terceiros.", "category": "guideline", "icon": "edit-document-outline", "order": 164, "outcomes": [ "Melhor compreensão dos princípios das diretrizes de integração de parceiros", "Abordagem normalizada utilizando as Diretrizes de Integração de Parceiros", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Estabelecer processos de integração e orientações para colaborar com os parceiros, incluindo a integração técnica, a partilha de dados e o apoio.", "Monitorize o desempenho e a conformidade da API do parceiro para garantir a fiabilidade e o alinhamento com a sua estratégia de API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "architecture-decision", "documentation", "platform-config", "metrics" ] }, { "index": 4, "id": "api-design", "slug": "method/api-design", "icon": "api", "title": "Conceção da solução de integração", "description": "Conceber o contrato de interface, os esquemas, os payloads e os padroes de interacao para o estilo de integracao selecionado.", "whyItMatters": "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.", "applyInWork": "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": [ { "text": "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs.", "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas" }, { "text": "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.", "resourceId": "interactionCanvas", "resourceTitle": "Canvas de Interação", "canvasId": "interactionCanvas" }, { "text": "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.", "resourceId": "restCanvas", "resourceTitle": "Canvas REST", "canvasId": "restCanvas" }, { "text": "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.", "resourceId": "eventCanvas", "resourceTitle": "Canvas de Eventos", "canvasId": "eventCanvas" }, { "text": "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.", "resourceId": "graphqlCanvas", "resourceTitle": "Canvas GraphQL", "canvasId": "graphqlCanvas" }, { "text": "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.", "resourceId": "api-design-principles", "resourceTitle": "Princípios de conceção da API", "canvasId": null }, { "text": "Aplique abordagens do tipo ‘contrato primeiro’ ou ‘design primeiro’ para capturar e validar o contrato de interface da API antes da implementação.", "resourceId": "contract-first-design", "resourceTitle": "Primeira conceção do contrato", "canvasId": null }, { "text": "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.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "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." ], "criteria": [ "architecture-patterns-validated", "hide-backend-discrepancies", "design-reflects-business-value", "api-consistency" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." } ], "baseTitle": "Conceção da API - Conceber APIs que proporcionem valor", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "design", "stakeholders": [ { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "lead", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "core", "responsibilities": [] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "core", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "integration-style-selection-guide", "slug": "resources/integration-style-selection-guide", "title": "Guia de seleção do estilo de implementação", "description": "Orientação para escolher entre API, evento, ficheiro, stream, produto de dados, integração direta ou estilos de implementação híbridos com base nos requisitos e restrições.", "category": "guideline", "icon": "edit-document-outline", "order": 180, "outcomes": [ "Estilo de implementação de integração justificado", "Compromissos documentados entre opções de estilo de implementação", "Estilo selecionado rastreável aos requisitos dos utilizadores, da plataforma, dos dados e da operação" ], "steps": [ "Compare estilos de implementação viáveis face a necessidades de latência, volume, acoplamento, propriedade dos dados, atualidade, governação e operabilidade.", "Identifique quando API, evento, ficheiro, stream, produto de dados, integração direta ou abordagens híbridas se ajustam ao caso de utilização.", "Documente restrições, riscos e dependências da plataforma para o estilo de implementação selecionado.", "Registe por que motivo as alternativas rejeitadas não foram selecionadas." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "restCanvas", "slug": "resources/rest-canvas", "title": "Canvas REST", "description": "Conceber APIs utilizando os princípios RESTful, definindo recursos, verbos e exemplos de pedidos e respostas.", "category": "canvas", "icon": "dashboard-outline", "order": 10, "outcomes": [ "Conceção consistente da API RESTful", "Recursos definidos e suas interações", "Exemplos de pedidos e respostas para maior clareza" ], "steps": [ "Identificar os principais recursos expostos pela API", "Definir a estrutura do modelo de recursos da API", "Especificar os verbos HTTP utilizados para interagir com os recursos", "Fornecer exemplos de pedidos e respostas para cada verbo" ], "canvasId": "restCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "eventCanvas", "slug": "resources/event-canvas", "title": "Canvas de Eventos", "description": "Conceber APIs orientadas para eventos, definindo eventos, accionadores e lógica de processamento.", "category": "canvas", "icon": "dashboard-outline", "order": 12, "outcomes": [ "Arquitetura orientada para eventos definida", "Limpar os accionadores de eventos e a lógica de processamento", "Melhoria da capacidade de resposta a alterações em tempo real" ], "steps": [ "Identificar os principais eventos do sistema", "Definir accionadores para cada evento", "Descrever a lógica de processamento back-end para eventos", "Especificar os resultados ou reconhecimentos resultantes" ], "canvasId": "eventCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "graphqlCanvas", "slug": "resources/graphql-canvas", "title": "Canvas GraphQL", "description": "Conceber APIs GraphQL definindo tipos, consultas, mutações e subscrições.", "category": "canvas", "icon": "dashboard-outline", "order": 11, "outcomes": [ "Conceção da API GraphQL estruturada", "Tipos definidos e suas relações", "Limpar consultas, mutações e subscrições" ], "steps": [ "Que problemas estão os utilizadores de API a tentar resolver? De que dados necessitam?", "Definir tipos GraphQL e seus atributos: Quais são os principais tipos expostos (por exemplo, utilizador, encomenda, produto)?", "Mapear relações entre tipos: Como é que os tipos se relacionam uns com os outros em consultas aninhadas?", "Especificar consultas para a recuperação de dados", "Definir mutações para a modificação de dados: Que operações irão modificar os dados (por exemplo, criar, atualizar, eliminar)?", "Assinaturas de esboços para actualizações em tempo real", "Definir autenticação e autorização: Quem pode aceder a que campos ou tipos?", "Considerar se existem restrições de paginação, filtragem ou limitação de taxa" ], "canvasId": "graphqlCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "contract-first-design", "slug": "resources/contract-first-design", "title": "Primeira conceção do contrato", "description": "Uma diretriz que defende abordagens API-first utilizando contratos formais (por exemplo, OpenAPI) para alinhar as partes interessadas antes do desenvolvimento.", "category": "guideline", "icon": "edit-document-outline", "order": 146, "outcomes": [ "Melhor compreensão dos princípios de conceção da primeira fase do contrato", "Abordagem normalizada utilizando a conceção orientada por contrato", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar." ], "canvasId": null, "sourcePath": "src/snippets/api-contract-example.yaml", "sourceUrl": null, "contentMarkdown": "openapi: 3.0.3\r\ninfo:\r\n title: Sample Catalog API\r\n version: 1.0.0\r\n description: |\r\n Starter example for a read-only APIOps Cycles API.\r\n This example keeps the contract audit-friendly and easy to extend.\r\nservers:\r\n - url: /v1\r\n description: Versioned API base path\r\ntags:\r\n - name: catalog\r\n description: Browse and search catalog items\r\npaths:\r\n /items:\r\n get:\r\n tags: [catalog]\r\n summary: List catalog items\r\n description: Returns a paginated list of public catalog items.\r\n operationId: listItems\r\n parameters:\r\n - $ref: \"#/components/parameters/searchTerm\"\r\n - $ref: \"#/components/parameters/categoryId\"\r\n - $ref: \"#/components/parameters/page\"\r\n - $ref: \"#/components/parameters/pageSize\"\r\n responses:\r\n \"200\":\r\n description: Item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n examples:\r\n default:\r\n value:\r\n data:\r\n - itemId: item-123\r\n slug: blue-widget\r\n name: Blue Widget\r\n status: published\r\n page:\r\n number: 1\r\n size: 20\r\n totalItems: 1\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"429\":\r\n $ref: \"#/components/responses/TooManyRequests\"\r\n /items/{itemId}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by id\r\n description: Returns a single public catalog item by opaque identifier.\r\n operationId: getItemById\r\n parameters:\r\n - $ref: \"#/components/parameters/itemId\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /items/by-slug/{slug}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by slug\r\n description: Returns a single item by public slug.\r\n operationId: getItemBySlug\r\n parameters:\r\n - $ref: \"#/components/parameters/slug\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /categories/{categoryId}/items:\r\n get:\r\n tags: [catalog]\r\n summary: List items in category\r\n description: Returns public items in a category.\r\n operationId: listItemsByCategory\r\n parameters:\r\n - $ref: \"#/components/parameters/categoryId\"\r\n responses:\r\n \"200\":\r\n description: Category item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\ncomponents:\r\n parameters:\r\n itemId:\r\n name: itemId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: item-123\r\n slug:\r\n name: slug\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9]+(?:-[a-z0-9]+)*$\"\r\n example: blue-widget\r\n categoryId:\r\n name: categoryId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: home-goods\r\n searchTerm:\r\n name: searchTerm\r\n in: query\r\n required: false\r\n schema:\r\n type: string\r\n minLength: 1\r\n example: widget\r\n page:\r\n name: page\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n default: 1\r\n pageSize:\r\n name: pageSize\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n maximum: 100\r\n default: 20\r\n responses:\r\n BadRequest:\r\n description: Validation failed\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n examples:\r\n default:\r\n value:\r\n code: BAD_REQUEST\r\n message: Invalid request\r\n NotFound:\r\n description: Resource not found\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n TooManyRequests:\r\n description: Rate limit exceeded\r\n headers:\r\n Retry-After:\r\n schema:\r\n type: integer\r\n description: Seconds until the next allowed request.\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n schemas:\r\n ItemListResponse:\r\n type: object\r\n required: [data, page]\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/ItemSummary\"\r\n page:\r\n $ref: \"#/components/schemas/Page\"\r\n ItemSummary:\r\n type: object\r\n required: [itemId, slug, name, status]\r\n properties:\r\n itemId:\r\n type: string\r\n slug:\r\n type: string\r\n name:\r\n type: string\r\n status:\r\n type: string\r\n enum: [published, hidden]\r\n ItemDetail:\r\n allOf:\r\n - $ref: \"#/components/schemas/ItemSummary\"\r\n - type: object\r\n properties:\r\n description:\r\n type: string\r\n categories:\r\n type: array\r\n items:\r\n type: string\r\n variants:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/Variant\"\r\n Variant:\r\n type: object\r\n required: [variantId, sku, price, inventory]\r\n properties:\r\n variantId:\r\n type: string\r\n sku:\r\n type: string\r\n price:\r\n $ref: \"#/components/schemas/Price\"\r\n inventory:\r\n $ref: \"#/components/schemas/Inventory\"\r\n Price:\r\n type: object\r\n required: [amount, currency]\r\n properties:\r\n amount:\r\n type: number\r\n format: decimal\r\n currency:\r\n type: string\r\n example: EUR\r\n Inventory:\r\n type: object\r\n required: [available]\r\n properties:\r\n available:\r\n type: integer\r\n minimum: 0\r\n reserved:\r\n type: integer\r\n minimum: 0\r\n source:\r\n type: string\r\n Page:\r\n type: object\r\n required: [number, size, totalItems]\r\n properties:\r\n number:\r\n type: integer\r\n size:\r\n type: integer\r\n totalItems:\r\n type: integer\r\n ErrorResponse:\r\n type: object\r\n required: [code, message]\r\n properties:\r\n code:\r\n type: string\r\n message:\r\n type: string\r\n", "draft": true } ], "evidence": [ "spec", "contract", "design-artifact", "documentation" ] }, { "index": 5, "id": "api-delivery", "slug": "method/api-delivery", "icon": "code", "title": "Entrega e operações da integração", "description": "Construir, testar, automatizar, disponibilizar e operar a capacidade de integracao usando o estilo de implementacao selecionado e o contrato de interface validado.", "whyItMatters": "Mesmo os melhores conceções de API falham se a entrega for inconsistente. Esta estação assegura que as suas APIs são construídas com qualidade, testadas exaustivamente e implementadas de forma fiável - permitindo iterações mais rápidas e maior confiança.", "applyInWork": "Fornecer estruturas de codificação, bibliotecas e normas para a implementação de API. Implementar pipelines de CI/CD, estruturas de garantia de qualidade e ferramentas de automatização da disponibilização.", "outcomes": [ "APIs implementadas utilizando estruturas e padrões testados", "Pipelines de CI/CD fiáveis e automatizados", "Testes funcionais e não funcionais integrados", "Condutas de entrega seguras e conformes" ], "steps": [ { "text": "Utilize as Melhores Práticas de Desenvolvimento de API como orientação para implementar o contrato validado com frameworks e bibliotecas estabelecidos, garantindo que o resultado seja reutilizável e sustentável.", "resourceId": "api-development-best-practices", "resourceTitle": "Boas práticas de desenvolvimento de API", "canvasId": null }, { "text": "Construa a implementação da API a partir do contrato validado usando frameworks, bibliotecas e padrões da equipa estabelecidos.", "resourceId": "api-development-best-practices", "resourceTitle": "Boas práticas de desenvolvimento de API", "canvasId": null }, { "text": "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "resourceId": "api-testing-best-practices", "resourceTitle": "Boas práticas de teste de API", "canvasId": null }, { "text": "Utilize pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null }, { "text": "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "resourceId": "api-security-best-practices", "resourceTitle": "Boas práticas de segurança da API", "canvasId": null }, { "text": "Utilize a lista de verificação de auditoria da API para garantir que a API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "questions": [ "Utilize as Melhores Práticas de Desenvolvimento de API como orientação para implementar o contrato validado com frameworks e bibliotecas estabelecidos, garantindo que o resultado seja reutilizável e sustentável.", "Construa a implementação da API a partir do contrato validado usando frameworks, bibliotecas e padrões da equipa estabelecidos.", "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Utilize pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "Utilize a lista de verificação de auditoria da API para garantir que a API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Fornecer estruturas de codificação, bibliotecas e normas para a implementação de API. Implementar pipelines de CI/CD, estruturas de garantia de qualidade e ferramentas de automatização da disponibilização.", "Mesmo os melhores conceções de API falham se a entrega for inconsistente. Esta estação assegura que as suas APIs são construídas com qualidade, testadas exaustivamente e implementadas de forma fiável - permitindo iterações mais rápidas e maior confiança." ], "criteria": [ "architecture-patterns-validated", "hide-backend-discrepancies", "design-reflects-business-value", "api-consistency" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." } ], "baseTitle": "Entrega da API - Fornecer APIs seguras e fiáveis", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "delivery", "stakeholders": [ { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "lead", "responsibilities": [] }, { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "partner-specialist", "sourceKey": "partner-specialist", "sourceStakeholderId": "partner-specialist", "title": "Gestor de parceiros ou fornecedores", "description": "Coordena relações com parceiros, fornecedores ou prestadores externos que influenciam a estratégia e entrega da capacidade ou API.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "api-development-best-practices", "slug": "resources/api-development-best-practices", "title": "Boas práticas de desenvolvimento de API", "description": "Orientações de implementação para transformar um contrato de interface da API validado numa base de código de API consistente e sustentável, utilizando bibliotecas padrão, padrões reutilizáveis e fluxos de trabalho de desenvolvimento alinhados.", "category": "guideline", "icon": "edit-document-outline", "order": 112, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de desenvolvimento de API", "Abordagem normalizada utilizando as boas práticas de desenvolvimento de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplique essas práticas ao contrato de interface da API validado e ao plano de implementação antes do início da codificação.", "Utilize frameworks, bibliotecas e padrões de codificação estabelecidos para implementar o contrato de forma consistente e sustentável." ], "canvasId": null, "sourcePath": "src/snippets/pt/api-design-principles-guidance.md", "sourceUrl": null, "contentMarkdown": "## Como iniciar o trabalho de entrega da API com base nas fases anteriores (“etapas”)\r\nUtilize estas orientações no início da `API Delivery` (entrega da API), após a revisão e aceitação do contrato da API (por exemplo, OpenAPI) e dos principais resultados das etapas anteriores.\r\nO objetivo não é desenvolver a implementação de forma isolada. O objetivo é transformar os resultados acordados nas etapas anteriores em uma estrutura de código concreta, regras de validação, comportamento em tempo de execução e decisões relativas à entrega do produto API.\r\n\r\n---\r\n\r\n### 1. Comece a partir do contrato validado\r\n- Trate o contrato de API validado como o principal ponto de referência para as decisões de implementação.\r\n- Mantenha o contrato e a implementação alinhados ao longo de toda a entrega do produto API.\r\n- Use o contrato para orientar a validação de solicitações, o mapeamento de respostas, a documentação e os testes.\r\n\r\n---\r\n\r\n### 2. Use os resultados do domínio para preservar o significado comercial\r\n- Use os resultados do `Domain Canvas` para orientar a nomenclatura, como a implementação é dividida em responsabilidades comerciais claras e como diferentes sistemas de back-end são conectados sem expor suas diferenças.\r\n- Preserve os significados validados de entidades, atributos, status e regras de fonte de verdade.\r\n- Evite vazar modelos específicos do back-end ou inconsistências para a API pública.\r\n\r\n---\r\n\r\n### 3. Use os resultados da jornada para preservar fluxos críticos\r\n- Use os resultados do `Customer Journey Canvas` para identificar quais fluxos de usuários são mais importantes para serem atendidos primeiro.\r\n- Use os resultados da `API Consumer Experience` para manter a API compreensível, previsível e fácil de integrar.\r\n- Deixe que as prioridades de jornada acordadas decidam quais caminhos de implementação precisam da maior confiabilidade, menor latência, erros mais claros e maior foco operacional.\r\n\r\n---\r\n\r\n### 4. Use os resultados da Proposta de Valor para preservar o valor para o consumidor\r\n- Use os resultados do `API Value Proposition Canvas` para manter a implementação focada nas dores, ganhos e recursos da API acordados.\r\n- Preserve os significados dos campos, o comportamento e as promessas que tornaram a API valiosa nas etapas anteriores.\r\n- Garanta que o tratamento de erros, a atualização e a nomenclatura apoiem tanto a experiência do desenvolvedor pretendida quanto o caso de uso de negócios.\r\n\r\n---\r\n\r\n### 5. Use os resultados da arquitetura para moldar as decisões de tempo de execução\r\n- Use os resultados do `Business Impact Canvas` para orientar as decisões sobre resiliência, tempo limite, fallback e degradação.\r\n- Use os resultados do `Locations Canvas` para orientar os limites de rede, limites de confiança, caminhos de acesso e restrições de implantação.\r\n- Use os resultados do `Capacity Canvas` para orientar limites de taxa, cache, escalonamento e comportamento em picos de carga.\r\n- Use as orientações do `API Metrics And Analytics` para decidir o que deve ser observado desde a primeira implementação em diante.\r\n\r\n---\r\n\r\n### 6. Use os resultados do projeto de interação e protocolo para moldar a estrutura do código\r\n- Use os resultados do `Interaction Canvas` para evitar implementar estilos de interação não suportados prematuramente.\r\n- Use os resultados do projeto `REST`, `Event` ou `GraphQL` para moldar o comportamento de solicitação, resposta e validação específico do protocolo.\r\n- Reflete o estilo de interação selecionado claramente na estrutura do código, nas responsabilidades e na estratégia de testes.\r\n\r\n---\r\n\r\n### 7. Usa os resultados da auditoria para melhorar a entrega antes que a codificação avance demais\r\n- Usa as conclusões da auditoria para remover ambiguidades antes que a implementação se espalhe pela base de código.\r\n- Corrige regras de solicitação pouco claras, validações ausentes, contratos de erro fracos e lacunas operacionais logo no início.\r\n- Trate a auditoria como um ciclo de melhoria de projeto antes da produção, não apenas como uma etapa de decisão final.\r\n\r\n---\r\n\r\n### 8. Aplique as orientações e, em seguida, resuma\r\n- Aplique estas orientações à API atual e ao plano de implementação.\r\n- Resuma as implicações para a estrutura do código, validação de solicitações, integração de fontes, segurança, monitoramento e alertas, e testes.\r\n- Não crie um artefato de entrega separado, a menos que a equipe ou o usuário precise especificamente de um.\r\n", "draft": true }, { "id": "api-testing-best-practices", "slug": "resources/api-testing-best-practices", "title": "Boas práticas de teste de API", "description": "Diretrizes para a implementação de testes automatizados funcionais, de desempenho e de segurança ao longo do ciclo de vida da API.", "category": "guideline", "icon": "edit-document-outline", "order": 133, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de teste de API", "Abordagem normalizada utilizando as boas práticas de teste de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Integrar testes funcionais e não funcionais no pipeline CI/CD para garantir que as APIs cumprems normas de qualidade.", "Utilizar ferramentas de teste automatizadas para validar a funcionalidade, a segurança e o desempenho da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "apiops-CI-CD-for-apis", "slug": "resources/apiops-CI-CD-for-apis", "title": "APIOps CI/CD para APIs", "description": "Orientação de disponibilização que integra tarefas do ciclo de vida da API - design, teste, governação - em pipelines de integração e entrega contínuas.", "category": "guideline", "icon": "edit-document-outline", "order": 140, "outcomes": [ "Melhor compreensão dos princípios de CI/CD para APIs", "Abordagem normalizada utilizando CI/CD para APIs", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilizar pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-security-best-practices", "slug": "resources/api-security-best-practices", "title": "Boas práticas de segurança da API", "description": "Um conjunto de controlos acionáveis para proteger APIs, incluindo autenticação, autorização, encriptação, limitação de taxas e verificações de conformidade ao nível do pipeline.", "category": "guideline", "icon": "edit-document-outline", "order": 130, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de segurança da API", "Abordagem normalizada utilizando as boas práticas de segurança da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "Implemente medidas de segurança como autenticação, autorização, encriptação e limitação de taxas para proteger as APIs de ameaças.", "Implementar verificações de segurança automatizadas e validações de conformidade no pipeline CI/CD para garantir que as APIs são seguras e compatíveis." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "partner-integration-guidelines", "slug": "resources/partner-integration-guidelines", "title": "Diretrizes de integração de parceiros", "description": "Listas de verificação de integração e padrões de comunicação para gerir os aspectos técnicos e legais das relações com APIs de terceiros.", "category": "guideline", "icon": "edit-document-outline", "order": 164, "outcomes": [ "Melhor compreensão dos princípios das diretrizes de integração de parceiros", "Abordagem normalizada utilizando as Diretrizes de Integração de Parceiros", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Estabelecer processos de integração e orientações para colaborar com os parceiros, incluindo a integração técnica, a partilha de dados e o apoio.", "Monitorize o desempenho e a conformidade da API do parceiro para garantir a fiabilidade e o alinhamento com a sua estratégia de API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "implementation", "pipeline-config", "test-report", "security-report" ] }, { "index": 6, "id": "api-audit", "slug": "method/api-audit", "icon": "check-box-outline", "title": "Garantia de prontidão da integração", "description": "Assegure a prontidão, a governação, a qualidade, a segurança, a conformidade e as evidências operacionais da integração antes da disponibilização.", "whyItMatters": "As APIs são produtos de longa duração e devem atender às expectativas de qualidade, consistência e conformidade. A auditoria conecta as decisões de conceção, a implementação e a prontidão operacional a padrões definidos, reduzindo o risco antes da exposição.", "applyInWork": "Estabeleça um processo de auditoria consistente que avalie a prontidão da API em todas as etapas do ciclo de vida usando critérios, evidências e padrões definidos. Garanta que as lacunas sejam identificadas antecipadamente e resolvidas antes da publicação.", "outcomes": [ "As APIs cumprems normas internas e externas", "Documentação clara das decisões de conceção e implementação da API", "Segurança, desempenho e conformidade validados", "Redução do risco de problemas na produção" ], "steps": [ { "text": "Realizar auditorias para garantir que as APIs cumprems normas organizacionais, técnicas e legais antes da publicação.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null }, { "text": "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas.", "resourceId": "api-compliance-best-practices", "resourceTitle": "Boas práticas de conformidade da API", "canvasId": null }, { "text": "Colaborar com as equipas de governação e especialistas no domínio para garantir que as APIs estão prontas para produção.", "resourceTitle": "", "canvasId": null } ], "questions": [ "Realizar auditorias para garantir que as APIs cumprems normas organizacionais, técnicas e legais antes da publicação.", "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas.", "Colaborar com as equipas de governação e especialistas no domínio para garantir que as APIs estão prontas para produção.", "Estabeleça um processo de auditoria consistente que avalie a prontidão da API em todas as etapas do ciclo de vida usando critérios, evidências e padrões definidos. Garanta que as lacunas sejam identificadas antecipadamente e resolvidas antes da publicação.", "As APIs são produtos de longa duração e devem atender às expectativas de qualidade, consistência e conformidade. A auditoria conecta as decisões de conceção, a implementação e a prontidão operacional a padrões definidos, reduzindo o risco antes da exposição." ], "criteria": [ "architecture-patterns-validated", "design-reflects-business-value", "api-description-available", "api-consistency", "api-contract-tested" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-description-available", "title": "A interface e as suas capacidades estão documentadas de forma suficientemente clara para revisão, auditoria e onboarding.", "description": "The API and its exposed capabilities are described clearly enough for review, audit, and onboarding." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." }, { "id": "api-contract-tested", "title": "O contrato de interface foi validado e testado face aos requisitos funcionais e não funcionais.", "description": "The API contract is tested and meets functional and non-functional requirements." } ], "baseTitle": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "publishing", "stakeholders": [ { "id": "governance-specialist", "sourceKey": "governance-specialist", "sourceStakeholderId": "governance-specialist", "title": "Responsável pela governação API", "description": "Representa práticas de revisão, auditoria e governação em toda a organização para qualidade e conformidade das APIs.", "involvement": "lead", "responsibilities": [] }, { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "core", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "api-audit-checklist", "slug": "resources/api-audit-checklist", "title": "Lista de verificação de auditoria da API", "description": "Uma lista de verificação baseada no ciclo de vida para verificar a prontidão da API em design, entrega, publicação e conformidade utilizando critérios de auditoria e evidências definidos.", "category": "checklist", "icon": "check-box-outline", "order": 13, "outcomes": [ "Melhor compreensão dos princípios da lista de controlo de auditoria da API", "Abordagem normalizada utilizando a lista de verificação de auditoria da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilize a lista de verificação de auditoria da API para garantir que a conceção da API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Realize auditorias para avaliar a cobertura do ciclo de vida e verificar se a API satisfaz os padrões de negócio, conceção e operacionais.", "Certifique-se de que a documentação, os modelos de segurança, a configuração do gateway e os requisitos legais estejam claramente definidos, validados e comprovados por evidências." ], "canvasId": null, "sourcePath": "src/snippets/api-audit-checklist.json", "sourceUrl": null, "contentMarkdown": "{\r\n \"profiles\": {\r\n \"read-only\": {\r\n \"description\": \"API profile that is read-only and does not allow create, update, or delete operations.\"\r\n },\r\n \"full-crud\": {\r\n \"description\": \"General API profile that allows create, update, and delete operations.\"\r\n }\r\n },\r\n \"lifecycleStages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6\r\n }\r\n ],\r\n \"stages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1,\r\n \"items\": [\r\n {\r\n \"id\": \"based-on-clear-business-needs\",\r\n \"label\": \"API is based on clear business needs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiBusinessModelCanvas\",\r\n \"apiValuePropositionCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"design-artifact\",\r\n \"documentation\",\r\n \"research\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\",\r\n \"specs/canvases/api-product-strategy/apiBusinessModelCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"concept-items-audited\",\r\n \"label\": \"All concept checklist items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"strategy\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\",\r\n \"api-opportunity-documented\",\r\n \"api-reusability\",\r\n \"value-prop-validated\",\r\n \"consumer-segments-identified\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/concept-review-report.json\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2,\r\n \"items\": [\r\n {\r\n \"id\": \"versioning-decided\",\r\n \"label\": \"Versioning strategy decided and supported by gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VERSION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-versioning-best-practices\",\r\n \"apiops-CI-CD-for-apis\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"ci-cd\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"only-via-gateway\",\r\n \"label\": \"Only accessible via API gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-02\",\r\n \"REST-CAPACITY-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"businessImpactCanvas\",\r\n \"locationsCanvas\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"infra-config\",\r\n \"security-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"rate-limits-enforced\",\r\n \"label\": \"Rate limits are enforced\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CAPACITY-01\",\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"capacityCanvas\",\r\n \"api-security-best-practices\",\r\n \"scalable-infrastructure-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"runtime\",\r\n \"monitoring\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-platform-architecture/capacityCanvas.empty.json\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3,\r\n \"items\": [\r\n {\r\n \"id\": \"endpoint-descriptions-present\",\r\n \"label\": \"Endpoints have business value and feature descriptions\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"operationDescriptions\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\",\r\n \"api-opportunity-documented\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiValuePropositionCanvas\",\r\n \"customerJourneyCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"hides-raw-backend-data\",\r\n \"label\": \"API hides raw backend data and is designed for shared use\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"interactionCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/domainCanvas.empty.json\",\r\n \"specs/canvases/api-design/interactionCanvas.empty.json\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"design-consistent\",\r\n \"label\": \"API design is consistent with other APIs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-02\",\r\n \"REST-CX-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-design/restCanvas.empty.json\",\r\n \"docs/api/design/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"descriptive-english-naming\",\r\n \"label\": \"Data and attribute naming uses descriptive English\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"fieldNamesDescriptive\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"mandatory-fields-specified\",\r\n \"label\": \"Mandatory fields are specified\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"requiredFieldsPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"dates-use-iso\",\r\n \"label\": \"Dates use ISO format with timezone\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"dateFormatTimezone\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"general-data-uses-standard-values\",\r\n \"label\": \"General data uses standard values\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"standardizedEnumsOrPatterns\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"field-names-avoid-acronyms\",\r\n \"label\": \"Field names avoid acronyms and use full words\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"avoidAcronyms\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"create-returns-identifiers\",\r\n \"label\": \"Creating new resources returns identifiers\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is read-only and does not create resources.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"paths-max-two-resources\",\r\n \"label\": \"Endpoint paths contain max two resources or sub-resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"pathDepthMax\",\r\n \"maxDepth\": 2\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PATH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"examples-present\",\r\n \"label\": \"Endpoints and attributes include examples\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-for-create-update\",\r\n \"label\": \"POST is used for create or update\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose create or update operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-for-remove\",\r\n \"label\": \"DELETE is used to remove resources\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose delete operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-no-request-body\",\r\n \"label\": \"GET has no request body and returns content\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"getNoRequestBody\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-empty-returns-204\",\r\n \"label\": \"GET returns 204 if response body is empty\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current contract returns content for all GET operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-200\",\r\n \"label\": \"POST returns 200 OK when updating\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST updates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-201\",\r\n \"label\": \"POST returns 201 Created with ID on create\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST creates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-returns-204\",\r\n \"label\": \"DELETE returns 204 on success\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose DELETE operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"400-errors-specific\",\r\n \"label\": \"400 errors provide specific error information\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"errorResponsesSpecific\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-400-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"api-audit-checklist\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"401-unauthorized\",\r\n \"label\": \"401 Unauthorized for wrong credentials\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current public storefront contract is intentionally unauthenticated.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-401-01\",\r\n \"REST-SEC-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"403-forbidden\",\r\n \"label\": \"403 Forbidden for unauthorized operations\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current profile is public read-only and exposes no unauthorized operations.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-403-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-contains-schemas\",\r\n \"label\": \"Spec contains request and response schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"schemasPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"restCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"pseudo-identifiers\",\r\n \"label\": \"UUIDs or pseudo-identifiers instead of DB IDs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"opaqueIdentifiers\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-07\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"no-sensitive-data-in-urls\",\r\n \"label\": \"No sensitive data in URLs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"noSensitiveDataInPaths\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-06\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"http-methods-match-resources\",\r\n \"label\": \"HTTP methods only for intended resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"methodResourceConsistency\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\",\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4,\r\n \"items\": [\r\n {\r\n \"id\": \"design-items-audited\",\r\n \"label\": \"All prototype and design items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"design\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"design-reflects-business-value\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/production-readiness-review.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-validated-on-change\",\r\n \"label\": \"Spec validated on every change\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"validationWorkflowPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\",\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"schema-and-examples-pass\",\r\n \"label\": \"Schema and examples pass validation\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPassValidation\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-contract-tested\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\",\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"api-audit-checklist\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"uses-https\",\r\n \"label\": \"Uses HTTPS or encrypted protocols\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"auth-protection\",\r\n \"label\": \"Endpoints protected by authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"token-auth\",\r\n \"label\": \"Token-based authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"csrf-protection\",\r\n \"label\": \"Protected against CSRF\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-08\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-development-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"inputs-auto-validated\",\r\n \"label\": \"Inputs auto-validated by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"contract-first-design\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\",\r\n \"test\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"outputs-auto-escaped\",\r\n \"label\": \"Outputs auto-escaped by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"JSON APIs do not typically require output escaping in the same way as HTML rendering.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"encryption-in-transit\",\r\n \"label\": \"Encryption for data in transit and storage\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"infra-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"message-integrity\",\r\n \"label\": \"Message integrity implemented\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"monitoring\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5,\r\n \"items\": [\r\n {\r\n \"id\": \"published-via-api-management\",\r\n \"label\": \"Published via API management\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"ci-cd\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"visible-in-dev-portal\",\r\n \"label\": \"Visible in developer portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-community-engagement-strategies\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"docs-auto-generated\",\r\n \"label\": \"Docs auto-generated from spec and schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\",\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"documentation\",\r\n \"ci-cd\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/publishing/README.md\",\r\n \"docs/api/audit/design-audit.read-only.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-auto-updated\",\r\n \"label\": \"Spec auto-updated to gateway and dev portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"contract-first-design\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"gateway-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"official-domain\",\r\n \"label\": \"Published under official organization domain\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6,\r\n \"items\": []\r\n }\r\n ],\r\n \"guidelines\": [\r\n {\r\n \"id\": \"REST-CONTRACT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST implement endpoints, parameters, request bodies, response bodies, and error responses as defined in the validated OpenAPI contract.\",\r\n \"relatedAuditItems\": [\r\n \"spec-contains-schemas\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CONTRACT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST keep the implementation, published OpenAPI description, gateway configuration, and developer portal documentation aligned on every change.\",\r\n \"relatedAuditItems\": [\r\n \"docs-auto-generated\",\r\n \"spec-auto-updated\",\r\n \"spec-validated-on-change\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VALIDATION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate path parameters, query parameters, headers, and JSON request bodies against the OpenAPI schema before business processing.\",\r\n \"relatedAuditItems\": [\r\n \"mandatory-fields-specified\",\r\n \"400-errors-specific\",\r\n \"inputs-auto-validated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST expose business-oriented resources and attributes rather than raw backend tables, internal service payloads, or system-specific field names.\",\r\n \"relatedAuditItems\": [\r\n \"based-on-clear-business-needs\",\r\n \"hides-raw-backend-data\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST preserve validated meanings of entities, attributes, statuses, and source-of-truth rules across all endpoints and operations.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\",\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use descriptive English names for resources and attributes.\",\r\n \"relatedAuditItems\": [\r\n \"descriptive-english-naming\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST avoid unexplained acronyms in public field and resource names.\",\r\n \"relatedAuditItems\": [\r\n \"field-names-avoid-acronyms\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use ISO date-time values with timezone information where dates are exposed.\",\r\n \"relatedAuditItems\": [\r\n \"dates-use-iso\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API SHOULD use standard codes, controlled vocabularies, and standardized value sets where applicable.\",\r\n \"relatedAuditItems\": [\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST describe the business value and feature intent of each endpoint or capability.\",\r\n \"relatedAuditItems\": [\r\n \"endpoint-descriptions-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST include examples for endpoints, request bodies, response bodies, and key attributes.\",\r\n \"relatedAuditItems\": [\r\n \"examples-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API SHOULD use consistent pagination, filtering, sorting, and response conventions across resources.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-GET-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use GET for safe read-only operations and MUST NOT define a request body for GET operations.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-POST-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use POST for resource creation and other non-idempotent operations.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-PUT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use PUT only for full resource replacement.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-DELETE-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use DELETE to remove resources.\",\r\n \"relatedAuditItems\": [\r\n \"delete-for-remove\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PATH-01\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"resource-modeling\",\r\n \"requirement\": \"The REST API SHOULD keep endpoint paths shallow and avoid more than two resource or sub-resource levels unless explicitly justified.\",\r\n \"relatedAuditItems\": [\r\n \"paths-max-two-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-200-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 200 OK for successful reads and updates that include a response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"post-returns-200\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-201-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 201 Created and the created resource identifier when a new resource is created.\",\r\n \"relatedAuditItems\": [\r\n \"create-returns-identifiers\",\r\n \"post-returns-201\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 204 No Content for successful delete operations that do not return a body.\",\r\n \"relatedAuditItems\": [\r\n \"delete-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API SHOULD return 204 No Content for successful operations that intentionally return no response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-empty-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-400-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST define 400 Bad Request responses with specific and actionable validation error information.\",\r\n \"relatedAuditItems\": [\r\n \"400-errors-specific\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-401-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 401 Unauthorized for missing or invalid credentials.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-403-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 403 Forbidden for authenticated clients lacking sufficient permission.\",\r\n \"relatedAuditItems\": [\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VERSION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"versioning\",\r\n \"requirement\": \"The REST API MUST define a versioning strategy before production release, and the strategy MUST be supportable by the API gateway.\",\r\n \"relatedAuditItems\": [\r\n \"versioning-decided\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST require authentication for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use token-based authentication or another approved modern authentication mechanism for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"token-auth\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-03\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST enforce object-level and function-level authorization on every protected operation.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\",\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST mitigate OWASP API risks including broken object level authorization, broken function level authorization, injection, and unrestricted resource consumption.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"rate-limits-enforced\",\r\n \"no-sensitive-data-in-urls\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-05\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use HTTPS or another approved encrypted protocol for all traffic.\",\r\n \"relatedAuditItems\": [\r\n \"uses-https\",\r\n \"encryption-in-transit\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-06\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST NOT expose sensitive information in URLs, query strings, logs, or unnecessary response fields.\",\r\n \"relatedAuditItems\": [\r\n \"no-sensitive-data-in-urls\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-07\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API SHOULD use UUIDs or other non-sequential public identifiers where direct database identifiers would increase exposure risk.\",\r\n \"relatedAuditItems\": [\r\n \"pseudo-identifiers\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-08\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST implement CSRF protection where relevant to the authentication model and client interaction pattern.\",\r\n \"relatedAuditItems\": [\r\n \"csrf-protection\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST define and enforce rate limits, throttling, or quotas according to capacity expectations.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST implement resilience controls such as timeouts, fallback behavior, and degradation handling according to business impact.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-OBS-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"observability\",\r\n \"requirement\": \"The REST API MUST implement logs, metrics, and monitoring needed to observe validation failures, auth failures, traffic, latency, and dependency health.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published through an API management platform.\",\r\n \"relatedAuditItems\": [\r\n \"published-via-api-management\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be accessible only through approved API gateway paths and managed entry points.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API SHOULD be visible in a developer portal with documentation generated from the contract.\",\r\n \"relatedAuditItems\": [\r\n \"visible-in-dev-portal\",\r\n \"docs-auto-generated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published under an approved organizational domain.\",\r\n \"relatedAuditItems\": [\r\n \"official-domain\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate the specification, schema, and examples on every change.\",\r\n \"relatedAuditItems\": [\r\n \"spec-validated-on-change\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST pass concept, design, security, and production-readiness checks before release.\",\r\n \"relatedAuditItems\": [\r\n \"concept-items-audited\",\r\n \"design-items-audited\"\r\n ]\r\n }\r\n ]\r\n}\r\n", "draft": false }, { "id": "api-compliance-best-practices", "slug": "resources/api-compliance-best-practices", "title": "Boas práticas de conformidade da API", "description": "Garantir que as APIs cumprem conformidade legal, regulamentar e interna através de documentação, controlos e validações automatizadas.", "category": "guideline", "icon": "edit-document-outline", "order": 104, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de conformidade da API", "Abordagem normalizada utilizando as Melhores Práticas de Conformidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Documentar as medidas de conformidade e garantir que são comunicadas às partes interessadas e aos utilizadores.", "Implementar medidas para garantir que as APIs cumprem estes requisitos, incluindo encriptação de dados, controlos de acesso e pistas de auditoria.", "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "audit-report", "compliance-report", "security-report", "test-report" ] }, { "index": 7, "id": "api-publishing", "slug": "method/api-publishing", "icon": "deployed-code-outline", "title": "Publicacao e enablement da integracao", "description": "Publicar a capacidade de integracao para que as equipas a possam descobrir, avaliar, solicitar acesso, concluir o onboarding, reutiliza-la e obter suporte.", "whyItMatters": "A publicação é mais do que a disponibilização - trata-se de capacidade de descoberta, acesso e suporte. Se as APIs não forem publicadas corretamente, não serão utilizadas, reutilizadas ou protegidas de forma eficaz.", "applyInWork": "Permitir que as APIs sejam publicadas no ambiente relevante e ter mecanismos claros de registo e acesso (por exemplo, chaves de API, OAuth, planos de subscrição), dependendo dos segmentos de consumidores de API e dos requisitos de segurança e conformidade.", "outcomes": [ "APIs publicadas no ambiente correto (privado, parceiro, público)", "Processos claros de integração e registo da API", "Documentação, modelos e políticas de segurança disponíveis", "APIs prontas para escala e governação" ], "steps": [ { "text": "Publicar APIs nos gateways e ambientes adequados para apoiar a reutilização por vários consumidores de API.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null }, { "text": "Documentar a forma como os consumidores encontram e utilizam a API, incluindo processos de integração e registo.", "resourceId": "api-onboarding-best-practices", "resourceTitle": "Boas práticas de integração de API", "canvasId": null }, { "text": "Garantir que os modelos de segurança, a configuração da porta de ligação e os termos legais sejam claros e acessíveis aos consumidores.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "questions": [ "Publicar APIs nos gateways e ambientes adequados para apoiar a reutilização por vários consumidores de API.", "Documentar a forma como os consumidores encontram e utilizam a API, incluindo processos de integração e registo.", "Garantir que os modelos de segurança, a configuração da porta de ligação e os termos legais sejam claros e acessíveis aos consumidores.", "Permitir que as APIs sejam publicadas no ambiente relevante e ter mecanismos claros de registo e acesso (por exemplo, chaves de API, OAuth, planos de subscrição), dependendo dos segmentos de consumidores de API e dos requisitos de segurança e conformidade.", "A publicação é mais do que a disponibilização - trata-se de capacidade de descoberta, acesso e suporte. Se as APIs não forem publicadas corretamente, não serão utilizadas, reutilizadas ou protegidas de forma eficaz." ], "criteria": [ "audit-passed", "audit-reports-shared", "api-ready-for-publishing", "api-documentation-ready" ], "criteriaDetails": [ { "id": "audit-passed", "title": "A solução passa as verificações de qualidade, segurança, conformidade e prontidão.", "description": "The API passes compliance, security, and audit checks." }, { "id": "audit-reports-shared", "title": "As conclusões da auditoria e as decisões de correção são partilhadas com as partes interessadas relevantes.", "description": "Audit findings and remediation decisions are shared with the relevant stakeholders." }, { "id": "api-ready-for-publishing", "title": "A capacidade está pronta para ser publicada ou disponibilizada através do mecanismo de entrega selecionado.", "description": "The API is ready to be deployed and exposed through the intended gateways and environments." }, { "id": "api-documentation-ready", "title": "A documentação orientada para os utilizadores e os materiais de onboarding estão prontos.", "description": "Consumer-facing API documentation is complete enough for publishing and onboarding." } ], "baseTitle": "Publicação de API - Publique APIs com confiança", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "publishing", "stakeholders": [ { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "lead", "responsibilities": [] }, { "id": "partner-specialist", "sourceKey": "partner-specialist", "sourceStakeholderId": "partner-specialist", "title": "Gestor de parceiros ou fornecedores", "description": "Coordena relações com parceiros, fornecedores ou prestadores externos que influenciam a estratégia e entrega da capacidade ou API.", "involvement": "core", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "service-agreement-template", "slug": "resources/service-agreement-template", "title": "Modelo de contrato de serviço", "description": "Um formato de acordo personalizável que define expectativas, SLAs, responsabilidades e termos de acesso para o consumo de API.", "category": "guideline", "icon": "edit-document-outline", "order": 172, "outcomes": [ "Melhor compreensão dos princípios do modelo de contrato de prestação de serviços", "Abordagem normalizada utilizando o modelo de contrato de serviços", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Defina acordos de serviço que descrevam as expectativas, os níveis de serviço e as responsabilidades de cada API.", "Utilize formatos normalizados para criar contratos de serviço legíveis por máquina que sejam fáceis de partilhar e validar.", "Assegurar que os acordos de serviço são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "gateway-config", "developer-portal", "documentation", "release-record" ] }, { "index": 8, "id": "monitoring-and-improving", "slug": "method/monitoring-and-improving", "icon": "analytics-outline", "title": "Monitorização e melhoria da integração", "description": "Monitorize a fiabilidade da integração, a reutilização, os incidentes, o desempenho, os resultados dos consumidores e as necessidades de melhoria.", "whyItMatters": "A entrega da API não pára no lançamento. Sem monitorização, as equipas não podem melhorar a adoção, o desempenho ou o ROI. Esta estação garante que as APIs permaneçam úteis, seguras e evoluindo com as necessidades do negócio.", "applyInWork": "Criar quadros analíticos para acompanhar o desempenho e o envolvimento. Desenvolver ciclos de feedback, ferramentas de análise e estratégias de envolvimento para APIs.", "outcomes": [ "Métricas de desempenho e utilização definidas e controladas", "Ciclos de feedback do programador em vigor", "Questões identificadas e tratadas continuamente", "Iteração da API alinhada com as necessidades dos utilizadores" ], "steps": [ { "text": "Monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "resourceId": "api-metrics-and-analytics", "resourceTitle": "Métricas e análise de API", "canvasId": null }, { "text": "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API.", "resourceId": "api-community-engagement-strategies", "resourceTitle": "Estratégias de envolvimento da comunidade API", "canvasId": null }, { "text": "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null } ], "questions": [ "Monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua.", "Criar quadros analíticos para acompanhar o desempenho e o envolvimento. Desenvolver ciclos de feedback, ferramentas de análise e estratégias de envolvimento para APIs.", "A entrega da API não pára no lançamento. Sem monitorização, as equipas não podem melhorar a adoção, o desempenho ou o ROI. Esta estação garante que as APIs permaneçam úteis, seguras e evoluindo com as necessidades do negócio." ], "criteria": [ "api-documentation-ready", "consumer-support-ready", "legal-compliance-clear" ], "criteriaDetails": [ { "id": "api-documentation-ready", "title": "A documentação orientada para os utilizadores e os materiais de onboarding estão prontos.", "description": "Consumer-facing API documentation is complete enough for publishing and onboarding." }, { "id": "consumer-support-ready", "title": "Os processos de onboarding, suporte e comunicação para utilizadores estão prontos.", "description": "Registration, support, and communication processes are ready for API consumers." }, { "id": "legal-compliance-clear", "title": "Os requisitos legais, de privacidade e de conformidade para publicação ou disponibilização estão definidos e compreendidos.", "description": "Legal, privacy, and compliance requirements for publishing are defined and understood." } ], "baseTitle": "Monitorização e melhoria - para valor API", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "improving", "stakeholders": [ { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "lead", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "core", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [] }, { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "api-metrics-and-analytics", "slug": "resources/api-metrics-and-analytics", "title": "Métricas e análise de API", "description": "Um recurso para definir, recolher e analisar o desempenho da API e os dados de utilização para alinhar os KPIs técnicos com os resultados de negócio.", "category": "guideline", "icon": "edit-document-outline", "order": 119, "outcomes": [ "Melhor compreensão dos princípios de métrica e análise de API", "Abordagem normalizada utilizando métricas e análise de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação" ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-community-engagement-strategies", "slug": "resources/api-community-engagement-strategies", "title": "Estratégias de envolvimento da comunidade API", "description": "Um manual para promover a adoção de APIs, cultivando comunidades através de conteúdos, canais de apoio, ciclos de feedback e estratégias de envolvimento social.", "category": "guideline", "icon": "edit-document-outline", "order": 103, "outcomes": [ "Melhor compreensão dos princípios das estratégias de envolvimento da comunidade da API", "Abordagem normalizada utilizando as estratégias de envolvimento da comunidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Desenvolver estratégias de marketing para promover as APIs junto de públicos-alvo, incluindo redes sociais, blogues e webinars.", "Criar materiais promocionais (por exemplo, estudos de casos, histórias de sucesso) que realcem o valor e as vantagens das APIs.", "Criar materiais educativos (por exemplo, tutoriais, documentação) que expliquem as características, as vantagens e os padrões de utilização da API.", "Interagir com os utilizadores da API através de ciclos de feedback, canais de apoio e fóruns da comunidade para compreender as suas necessidades e melhorar a adoção da API.", "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "metrics", "consumer-feedback", "incident-report", "roadmap" ] } ] }, { "id": "automation-cycle", "slug": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação.", "purpose": "Transformar oportunidades de automação em fluxos de trabalho governados com utilizadores, plataformas, controlos, percursos de entrega, capacitação e monitorização claros.", "audiences": [], "audienceStakeholders": [ { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "lead", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [ { "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "role": "suggested-answer-owner" } ] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [ { "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "role": "suggested-answer-owner" } ] }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "core", "responsibilities": [] }, { "id": "customer-specialist", "sourceKey": "customer-specialist", "sourceStakeholderId": "customer-specialist", "title": "Representante de cliente ou parceiro", "description": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "involvement": "core", "responsibilities": [] }, { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "lead", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "core", "responsibilities": [] }, { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "core", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "core", "responsibilities": [ { "resourceId": "interactionCanvas", "resourceTitle": "Canvas de Interação", "canvasId": "interactionCanvas", "role": "suggested-answer-owner" } ] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "governance-specialist", "sourceKey": "governance-specialist", "sourceStakeholderId": "governance-specialist", "title": "Responsável pela governação API", "description": "Representa práticas de revisão, auditoria e governação em toda a organização para qualidade e conformidade das APIs.", "involvement": "lead", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "core", "responsibilities": [] } ], "entryCriteria": [ "business-goals-defined", "stakeholder-approval" ], "exitCriteria": [ "design-reflects-business-value", "automation-workflow-validated", "audit-passed" ], "entryCriteriaDetails": [ { "id": "business-goals-defined", "title": "Os objetivos de negócio estão definidos.", "description": "Business goals are defined." }, { "id": "stakeholder-approval", "title": "As partes interessadas relevantes concordam que vale a pena explorar e priorizar esta oportunidade de capacidade.", "description": "Relevant stakeholders agree this API opportunity is worth exploring and prioritizing." } ], "exitCriteriaDetails": [ { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "automation-workflow-validated", "title": "O workflow, as regras, as integrações e os contratos de interface relevantes foram validados e testados.", "description": "The workflow, rules, integrations, and relevant interface contracts have been validated and tested." }, { "id": "audit-passed", "title": "A solução passa as verificações de qualidade, segurança, conformidade e prontidão.", "description": "The API passes compliance, security, and audit checks." } ], "questionnaireResources": [ { "stationId": "api-product-strategy", "stationTitle": "Estratégia da oportunidade de automação", "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "suggestedAnswerOwner": { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [ { "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-product-strategy", "stationTitle": "Estratégia da oportunidade de automação", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "suggestedAnswerOwner": { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [ { "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-consumer-experience", "stationTitle": "Requisitos do processo e dos utilizadores", "resourceId": "consumerExperienceRequirementsCanvas", "resourceTitle": "Canvas de Requisitos da Experiência do Utilizador", "canvasId": "consumerExperienceRequirementsCanvas", "suggestedAnswerOwner": { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "consulted", "responsibilities": [ { "resourceId": "consumerExperienceRequirementsCanvas", "resourceTitle": "Canvas de Requisitos da Experiência do Utilizador", "canvasId": "consumerExperienceRequirementsCanvas", "role": "suggested-answer-owner" } ] } }, { "stationId": "api-design", "stationTitle": "Conceção do fluxo de trabalho de automação", "resourceId": "interactionCanvas", "resourceTitle": "Canvas de Interação", "canvasId": "interactionCanvas", "suggestedAnswerOwner": { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "core", "responsibilities": [ { "resourceId": "interactionCanvas", "resourceTitle": "Canvas de Interação", "canvasId": "interactionCanvas", "role": "suggested-answer-owner" } ] } } ], "stations": [ { "index": 1, "id": "api-product-strategy", "slug": "method/api-product-strategy", "icon": "strategy-outline", "title": "Estratégia da oportunidade de automação", "description": "Identifique e priorize oportunidades de automação por valor, viabilidade, risco, propriedade e impacto esperado no processo.", "whyItMatters": "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais.", "applyInWork": "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "outcomes": [ "Uma proposta de valor e um público-alvo da API simples", "Linguagem partilhada entre o produto, a conceção e a tecnologia", "Um argumento sólido ou um caso para financiamento/aprovação" ], "steps": [ { "text": "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas" }, { "text": "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas" }, { "text": "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas" }, { "text": "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "resourceId": "apiBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da API", "canvasId": "apiBusinessModelCanvas" } ], "questions": [ "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais." ], "criteria": [ "metrics-feedback-available", "business-goals-defined", "market-research-done", "stakeholder-approval" ], "criteriaDetails": [ { "id": "metrics-feedback-available", "title": "Sinais de mercado relevantes, feedback ou conhecimento operacional estão disponíveis para orientar esta oportunidade de capacidade.", "description": "Relevant market signals, feedback, or operational insights are available to guide this API opportunity." }, { "id": "business-goals-defined", "title": "Os objetivos de negócio estão definidos.", "description": "Business goals are defined." }, { "id": "market-research-done", "title": "A investigação de mercado identifica oportunidades de capacidade.", "description": "Market research identifies API opportunities." }, { "id": "stakeholder-approval", "title": "As partes interessadas relevantes concordam que vale a pena explorar e priorizar esta oportunidade de capacidade.", "description": "Relevant stakeholders agree this API opportunity is worth exploring and prioritizing." } ], "baseTitle": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "strategy", "stakeholders": [ { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "lead", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [ { "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "role": "suggested-answer-owner" } ] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [ { "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "role": "suggested-answer-owner" } ] }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "core", "responsibilities": [] }, { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false } ], "evidence": [ "design-artifact", "documentation", "research", "roadmap" ] }, { "index": 2, "id": "api-consumer-experience", "slug": "method/api-consumer-experience", "icon": "deployed-code-account-outline", "title": "Requisitos do processo e dos utilizadores", "description": "Recolha utilizadores do processo, funções, transferências, exceções, restrições e expectativas de serviço antes de conceber a automação.", "whyItMatters": "As APIs excelentes não funcionam apenas - elas são intuitivas. Quer o consumidor seja um programador interno, um parceiro externo ou um agente de IA, a sua experiência determina a adoção.\n\nSnum plano de experiência claro:\n- Grandes APIs ficam sem uso\n- As equipas perdem tempo a tentar adivinhar como utilizar a sua API\n- Os ciclos de feedback estão quebrados ou ausentes.\n\nEsta estação ajuda-o a ver a sua API através dos olhos dos seus consumidores.", "applyInWork": "Fornecer diretrizes, ferramentas e mecanismos de feedback para compreender, analisar e melhorar a experiência interna e externa dos programadores e parceiros.", "outcomes": [ "Identifique e dê prioridade aos seus consumidores de API", "Definir o percurso da experiência API", "Planeamento da integração, documentação e feedback", "Melhorar a adoção através de empatia genuína + Experiência do Programador (DX)" ], "steps": [ { "text": "Analise o Canvas da Proposta de Valor da API existente sob a perspectiva do consumidor da API. Mantenha as tarefas de negócios suportadas estáveis ​​e enriqueça os recursos que aliviam problemas e possibilitam ganhos com as preocupações do consumidor da API, para que elas possam orientar as decisões de conceção futuras.", "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas" }, { "text": "Utilize o Canvas do Percurso do Cliente para a jornada do consumidor da API, desde a descoberta e avaliação até a integração, resolução de problemas e uso contínuo.", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas" }, { "text": "Utilize a jornada resultante para melhorar a integração, a documentação, o suporte e os ciclos de feedback para o consumidor da API.", "resourceId": "api-onboarding-best-practices", "resourceTitle": "Boas práticas de integração de API", "canvasId": null } ], "questions": [ "Analise o Canvas da Proposta de Valor da API existente sob a perspectiva do consumidor da API. Mantenha as tarefas de negócios suportadas estáveis ​​e enriqueça os recursos que aliviam problemas e possibilitam ganhos com as preocupações do consumidor da API, para que elas possam orientar as decisões de conceção futuras.", "Utilize o Canvas do Percurso do Cliente para a jornada do consumidor da API, desde a descoberta e avaliação até a integração, resolução de problemas e uso contínuo.", "Utilize a jornada resultante para melhorar a integração, a documentação, o suporte e os ciclos de feedback para o consumidor da API.", "Fornecer diretrizes, ferramentas e mecanismos de feedback para compreender, analisar e melhorar a experiência interna e externa dos programadores e parceiros.", "As APIs excelentes não funcionam apenas - elas são intuitivas. Quer o consumidor seja um programador interno, um parceiro externo ou um agente de IA, a sua experiência determina a adoção.\n\nSnum plano de experiência claro:\n- Grandes APIs ficam sem uso\n- As equipas perdem tempo a tentar adivinhar como utilizar a sua API\n- Os ciclos de feedback estão quebrados ou ausentes.\n\nEsta estação ajuda-o a ver a sua API através dos olhos dos seus consumidores." ], "criteria": [ "api-opportunity-documented", "api-reusability", "hide-backend-discrepancies", "value-prop-validated", "consumer-segments-identified", "api-roadmap-defined" ], "criteriaDetails": [ { "id": "api-opportunity-documented", "title": "A oportunidade de capacidade está identificada e documentada.", "description": "Individual API opportunities are identified and documented." }, { "id": "api-reusability", "title": "A capacidade responde a uma necessidade clara de negócio e é reutilizável pelos utilizadores previstos.", "description": "The API meets a clear business need and is reusable for multiple API consumers." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "value-prop-validated", "title": "A proposta de valor da capacidade foi validada com partes interessadas de negócio e utilizadores.", "description": "The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders." }, { "id": "consumer-segments-identified", "title": "Os segmentos de utilizadores estão identificados.", "description": "API consumer segments (internal and external) are identified." }, { "id": "api-roadmap-defined", "title": "Está definido um roadmap de implementação de alto nível.", "description": "High-level roadmaps for API development are established." } ], "baseTitle": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "strategy", "stakeholders": [ { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "lead", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [] }, { "id": "customer-specialist", "sourceKey": "customer-specialist", "sourceStakeholderId": "customer-specialist", "title": "Representante de cliente ou parceiro", "description": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "involvement": "core", "responsibilities": [] }, { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "core", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "consulted", "responsibilities": [ { "resourceId": "consumerExperienceRequirementsCanvas", "resourceTitle": "Canvas de Requisitos da Experiência do Utilizador", "canvasId": "consumerExperienceRequirementsCanvas", "role": "suggested-answer-owner" } ] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false } ], "evidence": [ "design-artifact", "documentation", "consumer-feedback" ] }, { "index": 3, "id": "api-platform-architecture", "slug": "method/api-platform-architecture", "icon": "code-blocks-outline", "title": "Decisão de plataforma de automação", "description": "Escolher a plataforma de automacao, o runtime, a abordagem de integracao, os controlos de governacao e as restricoes operacionais.", "whyItMatters": "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência.", "applyInWork": "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "outcomes": [ "Corte APIs redundantes e reduza os custos da plataforma de nuvem", "Implementar uma governação consistente snum forte controlo do topo para a base", "Conceção para reutilização interna e escalabilidade externa" ], "steps": [ { "text": "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas" }, { "text": "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas" }, { "text": "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas" }, { "text": "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "resourceId": "api-metrics-and-analytics", "resourceTitle": "Métricas e análise de API", "canvasId": null } ], "questions": [ "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência." ], "criteria": [ "api-reusability", "hide-backend-discrepancies", "value-prop-validated", "consumer-segments-identified", "api-roadmap-defined" ], "criteriaDetails": [ { "id": "api-reusability", "title": "A capacidade responde a uma necessidade clara de negócio e é reutilizável pelos utilizadores previstos.", "description": "The API meets a clear business need and is reusable for multiple API consumers." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "value-prop-validated", "title": "A proposta de valor da capacidade foi validada com partes interessadas de negócio e utilizadores.", "description": "The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders." }, { "id": "consumer-segments-identified", "title": "Os segmentos de utilizadores estão identificados.", "description": "API consumer segments (internal and external) are identified." }, { "id": "api-roadmap-defined", "title": "Está definido um roadmap de implementação de alto nível.", "description": "High-level roadmaps for API development are established." } ], "baseTitle": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "architecture", "stakeholders": [ { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "lead", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "core", "responsibilities": [] }, { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "core", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "core", "responsibilities": [] }, { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "consulted", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "automation-operational-ownership-guide", "slug": "resources/automation-operational-ownership-guide", "title": "Guia de responsabilidade operacional da automatização", "description": "Orientação para definir responsabilidade, runbooks, supervisão, suporte, monitorização, controlo de alterações e responsabilidades de melhoria contínua para automatizações.", "category": "guideline", "icon": "edit-document-outline", "order": 185, "outcomes": [ "Modelo operacional claro para a automatização", "Responsabilidades de propriedade, suporte e escalamento atribuídas", "Práticas de monitorização e alteração prontas para operação em produção" ], "steps": [ "Defina responsáveis de negócio, técnicos e operacionais pela automatização.", "Documente runbooks, caminhos de suporte, sinais de monitorização, expectativas de serviço e regras de escalamento.", "Defina controlo de alterações e práticas de revisão para atualizações de workflow, plataforma e regras." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "architecture-decision", "documentation", "platform-config", "metrics" ] }, { "index": 4, "id": "api-design", "slug": "method/api-design", "icon": "api", "title": "Conceção do fluxo de trabalho de automação", "description": "Conceber o fluxo de trabalho de automacao, os gatilhos, os pontos de decisao, as integracoes, o tratamento de dados, os contratos de interface relevantes e os caminhos de excecao.", "whyItMatters": "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.", "applyInWork": "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": [ { "text": "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs.", "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas" }, { "text": "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.", "resourceId": "interactionCanvas", "resourceTitle": "Canvas de Interação", "canvasId": "interactionCanvas" }, { "text": "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.", "resourceId": "restCanvas", "resourceTitle": "Canvas REST", "canvasId": "restCanvas" }, { "text": "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.", "resourceId": "eventCanvas", "resourceTitle": "Canvas de Eventos", "canvasId": "eventCanvas" }, { "text": "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.", "resourceId": "graphqlCanvas", "resourceTitle": "Canvas GraphQL", "canvasId": "graphqlCanvas" }, { "text": "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.", "resourceId": "api-design-principles", "resourceTitle": "Princípios de conceção da API", "canvasId": null }, { "text": "Aplique abordagens do tipo ‘contrato primeiro’ ou ‘design primeiro’ para capturar e validar o contrato de interface da API antes da implementação.", "resourceId": "contract-first-design", "resourceTitle": "Primeira conceção do contrato", "canvasId": null }, { "text": "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.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "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." ], "criteria": [ "architecture-patterns-validated", "hide-backend-discrepancies", "design-reflects-business-value", "api-consistency" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." } ], "baseTitle": "Conceção da API - Conceber APIs que proporcionem valor", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "design", "stakeholders": [ { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "lead", "responsibilities": [] }, { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "core", "responsibilities": [ { "resourceId": "interactionCanvas", "resourceTitle": "Canvas de Interação", "canvasId": "interactionCanvas", "role": "suggested-answer-owner" } ] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [] }, { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "core", "responsibilities": [] }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "core", "responsibilities": [] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "process-workflow-design-guide", "slug": "resources/process-workflow-design-guide", "title": "Guia de desenho do processo e workflow", "description": "Orientação para modelar passos do processo, papéis, passagens de responsabilidade, pontos de decisão, estados, entradas, saídas e exceções que moldam um workflow de automatização.", "category": "guideline", "icon": "edit-document-outline", "order": 181, "outcomes": [ "Desenho claro do workflow de automatização", "Passos do processo e passagens de responsabilidade documentados antes da implementação", "Estados do workflow, entradas, saídas e caminhos de exceção compreendidos" ], "steps": [ "Mapeie o fluxo do processo atual e alvo, incluindo responsabilidades humanas e dos sistemas.", "Identifique gatilhos do workflow, estados, decisões, entradas de dados, saídas e critérios de conclusão.", "Documente passagens de responsabilidade entre utilizadores, sistemas, operações e papéis de suporte.", "Confirme que passos devem ser automatizados e quais exigem julgamento humano." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "decision-business-rules-guide", "slug": "resources/decision-business-rules-guide", "title": "Guia de decisões e regras de negócio", "description": "Orientação para captar regras, limiares, decisões, aprovações, verificações de elegibilidade e responsabilidade pelas regras no desenho de automatizações.", "category": "guideline", "icon": "edit-document-outline", "order": 182, "outcomes": [ "Decisões e regras de negócio explícitas", "Regras e limiares documentados com responsáveis", "Decisões da automatização rastreáveis a políticas, processos ou intenção de negócio" ], "steps": [ "Liste as decisões que a automatização deve tomar ou apoiar.", "Documente condições das regras, limiares, exceções, aprovações e pontos de escalamento.", "Identifique responsáveis pelas regras e governação de alterações para cada área de decisão." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "automation-trigger-handoff-exception-guide", "slug": "resources/automation-trigger-handoff-exception-guide", "title": "Guia de gatilhos, passagens de responsabilidade e exceções da automatização", "description": "Orientação para definir gatilhos de automatização, passagens para intervenção humana, tratamento de exceções, tentativas repetidas, ações compensatórias e caminhos de escalamento de suporte.", "category": "guideline", "icon": "edit-document-outline", "order": 183, "outcomes": [ "Gatilhos de automatização e caminhos de exceção definidos", "Passagens para intervenção humana e escalamentos de suporte estão explícitos", "Exceções, tentativas repetidas e ações compensatórias desenhadas antes da entrega" ], "steps": [ "Defina os eventos, calendários, ações de utilizadores ou estados de sistema que acionam a automatização.", "Mapeie passagens da automatização para utilizadores, operadores ou equipas de suporte.", "Documente exceções, regras de nova tentativa, comportamento de timeout e caminhos alternativos.", "Defina alertas e limiares de escalamento para resultados de automatização falhados ou ambíguos." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "spec", "contract", "design-artifact", "documentation" ] }, { "index": 5, "id": "api-delivery", "slug": "method/api-delivery", "icon": "code", "title": "Entrega e operacao da automacao", "description": "Construa, teste, disponibilize, documente e opere a automação com propriedade, controlos e caminhos de reversão claros.", "whyItMatters": "Mesmo os melhores conceções de API falham se a entrega for inconsistente. Esta estação assegura que as suas APIs são construídas com qualidade, testadas exaustivamente e implementadas de forma fiável - permitindo iterações mais rápidas e maior confiança.", "applyInWork": "Fornecer estruturas de codificação, bibliotecas e normas para a implementação de API. Implementar pipelines de CI/CD, estruturas de garantia de qualidade e ferramentas de automatização da disponibilização.", "outcomes": [ "APIs implementadas utilizando estruturas e padrões testados", "Pipelines de CI/CD fiáveis e automatizados", "Testes funcionais e não funcionais integrados", "Condutas de entrega seguras e conformes" ], "steps": [ { "text": "Utilize as Melhores Práticas de Desenvolvimento de API como orientação para implementar o contrato validado com frameworks e bibliotecas estabelecidos, garantindo que o resultado seja reutilizável e sustentável.", "resourceId": "api-development-best-practices", "resourceTitle": "Boas práticas de desenvolvimento de API", "canvasId": null }, { "text": "Construa a implementação da API a partir do contrato validado usando frameworks, bibliotecas e padrões da equipa estabelecidos.", "resourceId": "api-development-best-practices", "resourceTitle": "Boas práticas de desenvolvimento de API", "canvasId": null }, { "text": "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "resourceId": "api-testing-best-practices", "resourceTitle": "Boas práticas de teste de API", "canvasId": null }, { "text": "Utilize pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null }, { "text": "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "resourceId": "api-security-best-practices", "resourceTitle": "Boas práticas de segurança da API", "canvasId": null }, { "text": "Utilize a lista de verificação de auditoria da API para garantir que a API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "questions": [ "Utilize as Melhores Práticas de Desenvolvimento de API como orientação para implementar o contrato validado com frameworks e bibliotecas estabelecidos, garantindo que o resultado seja reutilizável e sustentável.", "Construa a implementação da API a partir do contrato validado usando frameworks, bibliotecas e padrões da equipa estabelecidos.", "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Utilize pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "Utilize a lista de verificação de auditoria da API para garantir que a API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Fornecer estruturas de codificação, bibliotecas e normas para a implementação de API. Implementar pipelines de CI/CD, estruturas de garantia de qualidade e ferramentas de automatização da disponibilização.", "Mesmo os melhores conceções de API falham se a entrega for inconsistente. Esta estação assegura que as suas APIs são construídas com qualidade, testadas exaustivamente e implementadas de forma fiável - permitindo iterações mais rápidas e maior confiança." ], "criteria": [ "architecture-patterns-validated", "hide-backend-discrepancies", "design-reflects-business-value", "api-consistency" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." } ], "baseTitle": "Entrega da API - Fornecer APIs seguras e fiáveis", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "delivery", "stakeholders": [ { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "lead", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "automation-testing-guide", "slug": "resources/automation-testing-guide", "title": "Guia de testes de automatização", "description": "Orientação para testar workflows automatizados, decisões, integrações, exceções, comportamento de rollback, supervisão e impacto nos utilizadores antes da publicação.", "category": "guideline", "icon": "edit-document-outline", "order": 184, "outcomes": [ "Comportamento da automatização validado", "Testes de workflow, regras, exceções e integração definidos", "Confiança na publicação para caminhos automatizados e assistidos por pessoas" ], "steps": [ "Crie testes para caminhos esperados, casos-limite, exceções, tentativas repetidas e passagens de responsabilidade.", "Valide regras de negócio e resultados de decisão com dados representativos.", "Teste rollback, recuperação, observabilidade e caminhos de intervenção manual.", "Inclua utilizadores e operadores em testes de aceitação quando a automatização altera práticas de trabalho." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "automation-operational-ownership-guide", "slug": "resources/automation-operational-ownership-guide", "title": "Guia de responsabilidade operacional da automatização", "description": "Orientação para definir responsabilidade, runbooks, supervisão, suporte, monitorização, controlo de alterações e responsabilidades de melhoria contínua para automatizações.", "category": "guideline", "icon": "edit-document-outline", "order": 185, "outcomes": [ "Modelo operacional claro para a automatização", "Responsabilidades de propriedade, suporte e escalamento atribuídas", "Práticas de monitorização e alteração prontas para operação em produção" ], "steps": [ "Defina responsáveis de negócio, técnicos e operacionais pela automatização.", "Documente runbooks, caminhos de suporte, sinais de monitorização, expectativas de serviço e regras de escalamento.", "Defina controlo de alterações e práticas de revisão para atualizações de workflow, plataforma e regras." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "automation-rollback-supervision-guide", "slug": "resources/automation-rollback-supervision-guide", "title": "Guia de rollback e supervisão da automatização", "description": "Orientação para desenhar caminhos de rollback, pausa, substituição manual, monitorização, supervisão e recuperação para automatizações.", "category": "guideline", "icon": "edit-document-outline", "order": 186, "outcomes": [ "Caminhos controlados de recuperação da automatização", "Comportamento de rollback, pausa e substituição manual documentado", "Necessidades de supervisão e responsabilidades de recuperação definidas" ], "steps": [ "Identifique ações que devem poder ser revertidas, pausadas ou substituídas manualmente.", "Defina procedimentos de rollback, compensação e recuperação para resultados de automatização falhados ou incorretos.", "Documente limiares de supervisão, alertas e pontos de decisão manual.", "Valide os procedimentos de recuperação antes da publicação." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "implementation", "pipeline-config", "test-report", "security-report" ] }, { "index": 6, "id": "api-audit", "slug": "method/api-audit", "icon": "check-box-outline", "title": "Revisão de prontidão da automação", "description": "Reveja a prontidão, a qualidade, o risco, a conformidade, a supervisão humana, as evidências e os critérios de disponibilização da automação.", "whyItMatters": "As APIs são produtos de longa duração e devem atender às expectativas de qualidade, consistência e conformidade. A auditoria conecta as decisões de conceção, a implementação e a prontidão operacional a padrões definidos, reduzindo o risco antes da exposição.", "applyInWork": "Estabeleça um processo de auditoria consistente que avalie a prontidão da API em todas as etapas do ciclo de vida usando critérios, evidências e padrões definidos. Garanta que as lacunas sejam identificadas antecipadamente e resolvidas antes da publicação.", "outcomes": [ "As APIs cumprems normas internas e externas", "Documentação clara das decisões de conceção e implementação da API", "Segurança, desempenho e conformidade validados", "Redução do risco de problemas na produção" ], "steps": [ { "text": "Realizar auditorias para garantir que as APIs cumprems normas organizacionais, técnicas e legais antes da publicação.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null }, { "text": "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas.", "resourceId": "api-compliance-best-practices", "resourceTitle": "Boas práticas de conformidade da API", "canvasId": null }, { "text": "Colaborar com as equipas de governação e especialistas no domínio para garantir que as APIs estão prontas para produção.", "resourceTitle": "", "canvasId": null } ], "questions": [ "Realizar auditorias para garantir que as APIs cumprems normas organizacionais, técnicas e legais antes da publicação.", "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas.", "Colaborar com as equipas de governação e especialistas no domínio para garantir que as APIs estão prontas para produção.", "Estabeleça um processo de auditoria consistente que avalie a prontidão da API em todas as etapas do ciclo de vida usando critérios, evidências e padrões definidos. Garanta que as lacunas sejam identificadas antecipadamente e resolvidas antes da publicação.", "As APIs são produtos de longa duração e devem atender às expectativas de qualidade, consistência e conformidade. A auditoria conecta as decisões de conceção, a implementação e a prontidão operacional a padrões definidos, reduzindo o risco antes da exposição." ], "criteria": [ "architecture-patterns-validated", "design-reflects-business-value", "api-description-available", "api-consistency", "api-contract-tested" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-description-available", "title": "A interface e as suas capacidades estão documentadas de forma suficientemente clara para revisão, auditoria e onboarding.", "description": "The API and its exposed capabilities are described clearly enough for review, audit, and onboarding." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." }, { "id": "api-contract-tested", "title": "O contrato de interface foi validado e testado face aos requisitos funcionais e não funcionais.", "description": "The API contract is tested and meets functional and non-functional requirements." } ], "baseTitle": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "publishing", "stakeholders": [ { "id": "governance-specialist", "sourceKey": "governance-specialist", "sourceStakeholderId": "governance-specialist", "title": "Responsável pela governação API", "description": "Representa práticas de revisão, auditoria e governação em toda a organização para qualidade e conformidade das APIs.", "involvement": "lead", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "core", "responsibilities": [] }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "consulted", "responsibilities": [] }, { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "consulted", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "automation-readiness-checklist", "slug": "resources/automation-readiness-checklist", "title": "Checklist de prontidão da automatização", "description": "Uma checklist para validar workflow de automatização, controlos, risco, conformidade, supervisão humana, evidências de teste, rollback, operações e prontidão para publicação.", "category": "checklist", "icon": "check-box-outline", "order": 187, "outcomes": [ "Prontidão da automatização documentada", "Lacunas de prontidão conhecidas e mitigações antes da publicação", "Evidências para qualidade, risco, conformidade, supervisão e aprovação operacional" ], "steps": [ "Reveja desenho do workflow, regras de negócio, controlos, acesso, tratamento de dados e caminhos de exceção.", "Verifique evidências de teste, procedimentos de rollback, modelo de supervisão e prontidão do suporte.", "Confirme responsabilidade, runbooks, monitorização, controlos de alteração e aprovação de publicação.", "Registe lacunas por resolver, decisões e riscos aceites antes da publicação." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-compliance-best-practices", "slug": "resources/api-compliance-best-practices", "title": "Boas práticas de conformidade da API", "description": "Garantir que as APIs cumprem conformidade legal, regulamentar e interna através de documentação, controlos e validações automatizadas.", "category": "guideline", "icon": "edit-document-outline", "order": 104, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de conformidade da API", "Abordagem normalizada utilizando as Melhores Práticas de Conformidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Documentar as medidas de conformidade e garantir que são comunicadas às partes interessadas e aos utilizadores.", "Implementar medidas para garantir que as APIs cumprem estes requisitos, incluindo encriptação de dados, controlos de acesso e pistas de auditoria.", "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "audit-report", "compliance-report", "security-report", "test-report" ] }, { "index": 7, "id": "api-publishing", "slug": "method/api-publishing", "icon": "deployed-code-outline", "title": "Rollout e enablement da automacao", "description": "Capacite utilizadores e operadores com descoberta, integração, instruções operacionais, caminhos de suporte e comunicação de alterações.", "whyItMatters": "A publicação é mais do que a disponibilização - trata-se de capacidade de descoberta, acesso e suporte. Se as APIs não forem publicadas corretamente, não serão utilizadas, reutilizadas ou protegidas de forma eficaz.", "applyInWork": "Permitir que as APIs sejam publicadas no ambiente relevante e ter mecanismos claros de registo e acesso (por exemplo, chaves de API, OAuth, planos de subscrição), dependendo dos segmentos de consumidores de API e dos requisitos de segurança e conformidade.", "outcomes": [ "APIs publicadas no ambiente correto (privado, parceiro, público)", "Processos claros de integração e registo da API", "Documentação, modelos e políticas de segurança disponíveis", "APIs prontas para escala e governação" ], "steps": [ { "text": "Publicar APIs nos gateways e ambientes adequados para apoiar a reutilização por vários consumidores de API.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null }, { "text": "Documentar a forma como os consumidores encontram e utilizam a API, incluindo processos de integração e registo.", "resourceId": "api-onboarding-best-practices", "resourceTitle": "Boas práticas de integração de API", "canvasId": null }, { "text": "Garantir que os modelos de segurança, a configuração da porta de ligação e os termos legais sejam claros e acessíveis aos consumidores.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "questions": [ "Publicar APIs nos gateways e ambientes adequados para apoiar a reutilização por vários consumidores de API.", "Documentar a forma como os consumidores encontram e utilizam a API, incluindo processos de integração e registo.", "Garantir que os modelos de segurança, a configuração da porta de ligação e os termos legais sejam claros e acessíveis aos consumidores.", "Permitir que as APIs sejam publicadas no ambiente relevante e ter mecanismos claros de registo e acesso (por exemplo, chaves de API, OAuth, planos de subscrição), dependendo dos segmentos de consumidores de API e dos requisitos de segurança e conformidade.", "A publicação é mais do que a disponibilização - trata-se de capacidade de descoberta, acesso e suporte. Se as APIs não forem publicadas corretamente, não serão utilizadas, reutilizadas ou protegidas de forma eficaz." ], "criteria": [ "audit-passed", "audit-reports-shared", "api-ready-for-publishing", "api-documentation-ready" ], "criteriaDetails": [ { "id": "audit-passed", "title": "A solução passa as verificações de qualidade, segurança, conformidade e prontidão.", "description": "The API passes compliance, security, and audit checks." }, { "id": "audit-reports-shared", "title": "As conclusões da auditoria e as decisões de correção são partilhadas com as partes interessadas relevantes.", "description": "Audit findings and remediation decisions are shared with the relevant stakeholders." }, { "id": "api-ready-for-publishing", "title": "A capacidade está pronta para ser publicada ou disponibilizada através do mecanismo de entrega selecionado.", "description": "The API is ready to be deployed and exposed through the intended gateways and environments." }, { "id": "api-documentation-ready", "title": "A documentação orientada para os utilizadores e os materiais de onboarding estão prontos.", "description": "Consumer-facing API documentation is complete enough for publishing and onboarding." } ], "baseTitle": "Publicação de API - Publique APIs com confiança", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "publishing", "stakeholders": [ { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "lead", "responsibilities": [] }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "core", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "automation-rollout-enablement-guide", "slug": "resources/automation-rollout-enablement-guide", "title": "Guia de rollout e enablement da automatização", "description": "Orientação para implementar automatizações com comunicação aos utilizadores, onboarding, instruções operacionais, caminhos de suporte, gestão da mudança e ciclos de feedback.", "category": "guideline", "icon": "edit-document-outline", "order": 188, "outcomes": [ "Utilizadores e operadores da automatização preparados", "Comunicação de rollout, onboarding e caminhos de suporte preparados", "Utilizadores e operadores compreendem como o trabalho muda após a publicação da automatização" ], "steps": [ "Defina públicos do rollout, calendário, canais de comunicação e necessidades de formação.", "Publique instruções operacionais, caminhos de suporte, orientação para exceções e contactos de escalamento.", "Planeie suporte de transição para utilizadores, operadores e responsáveis pelo processo.", "Recolha feedback após o rollout e alimente o backlog com melhorias." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "service-agreement-template", "slug": "resources/service-agreement-template", "title": "Modelo de contrato de serviço", "description": "Um formato de acordo personalizável que define expectativas, SLAs, responsabilidades e termos de acesso para o consumo de API.", "category": "guideline", "icon": "edit-document-outline", "order": 172, "outcomes": [ "Melhor compreensão dos princípios do modelo de contrato de prestação de serviços", "Abordagem normalizada utilizando o modelo de contrato de serviços", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Defina acordos de serviço que descrevam as expectativas, os níveis de serviço e as responsabilidades de cada API.", "Utilize formatos normalizados para criar contratos de serviço legíveis por máquina que sejam fáceis de partilhar e validar.", "Assegurar que os acordos de serviço são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "gateway-config", "developer-portal", "documentation", "release-record" ] }, { "index": 8, "id": "monitoring-and-improving", "slug": "method/monitoring-and-improving", "icon": "analytics-outline", "title": "Monitorização e melhoria da automação", "description": "Monitorize o desempenho da automação, exceções, fiabilidade, resultados dos utilizadores, impacto operacional e oportunidades de melhoria.", "whyItMatters": "A entrega da API não pára no lançamento. Sem monitorização, as equipas não podem melhorar a adoção, o desempenho ou o ROI. Esta estação garante que as APIs permaneçam úteis, seguras e evoluindo com as necessidades do negócio.", "applyInWork": "Criar quadros analíticos para acompanhar o desempenho e o envolvimento. Desenvolver ciclos de feedback, ferramentas de análise e estratégias de envolvimento para APIs.", "outcomes": [ "Métricas de desempenho e utilização definidas e controladas", "Ciclos de feedback do programador em vigor", "Questões identificadas e tratadas continuamente", "Iteração da API alinhada com as necessidades dos utilizadores" ], "steps": [ { "text": "Monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "resourceId": "api-metrics-and-analytics", "resourceTitle": "Métricas e análise de API", "canvasId": null }, { "text": "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API.", "resourceId": "api-community-engagement-strategies", "resourceTitle": "Estratégias de envolvimento da comunidade API", "canvasId": null }, { "text": "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null } ], "questions": [ "Monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua.", "Criar quadros analíticos para acompanhar o desempenho e o envolvimento. Desenvolver ciclos de feedback, ferramentas de análise e estratégias de envolvimento para APIs.", "A entrega da API não pára no lançamento. Sem monitorização, as equipas não podem melhorar a adoção, o desempenho ou o ROI. Esta estação garante que as APIs permaneçam úteis, seguras e evoluindo com as necessidades do negócio." ], "criteria": [ "api-documentation-ready", "consumer-support-ready", "legal-compliance-clear" ], "criteriaDetails": [ { "id": "api-documentation-ready", "title": "A documentação orientada para os utilizadores e os materiais de onboarding estão prontos.", "description": "Consumer-facing API documentation is complete enough for publishing and onboarding." }, { "id": "consumer-support-ready", "title": "Os processos de onboarding, suporte e comunicação para utilizadores estão prontos.", "description": "Registration, support, and communication processes are ready for API consumers." }, { "id": "legal-compliance-clear", "title": "Os requisitos legais, de privacidade e de conformidade para publicação ou disponibilização estão definidos e compreendidos.", "description": "Legal, privacy, and compliance requirements for publishing are defined and understood." } ], "baseTitle": "Monitorização e melhoria - para valor API", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "improving", "stakeholders": [ { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "lead", "responsibilities": [] }, { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "core", "responsibilities": [] }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "consulted", "responsibilities": [] } ], "resources": [ { "id": "automation-operational-ownership-guide", "slug": "resources/automation-operational-ownership-guide", "title": "Guia de responsabilidade operacional da automatização", "description": "Orientação para definir responsabilidade, runbooks, supervisão, suporte, monitorização, controlo de alterações e responsabilidades de melhoria contínua para automatizações.", "category": "guideline", "icon": "edit-document-outline", "order": 185, "outcomes": [ "Modelo operacional claro para a automatização", "Responsabilidades de propriedade, suporte e escalamento atribuídas", "Práticas de monitorização e alteração prontas para operação em produção" ], "steps": [ "Defina responsáveis de negócio, técnicos e operacionais pela automatização.", "Documente runbooks, caminhos de suporte, sinais de monitorização, expectativas de serviço e regras de escalamento.", "Defina controlo de alterações e práticas de revisão para atualizações de workflow, plataforma e regras." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-metrics-and-analytics", "slug": "resources/api-metrics-and-analytics", "title": "Métricas e análise de API", "description": "Um recurso para definir, recolher e analisar o desempenho da API e os dados de utilização para alinhar os KPIs técnicos com os resultados de negócio.", "category": "guideline", "icon": "edit-document-outline", "order": 119, "outcomes": [ "Melhor compreensão dos princípios de métrica e análise de API", "Abordagem normalizada utilizando métricas e análise de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação" ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "evidence": [ "metrics", "consumer-feedback", "incident-report", "roadmap" ] } ] } ], "lines": [ { "id": "business-opportunities-line", "slug": "business-opportunities-line", "title": "Linha oportunidades de negócio", "description": "Centra-se na identificação e aproveitamento de oportunidades de negócio através de APIs.", "icon": "", "color": "#26b309", "order": 1, "stations": [ "monitoring-and-improving", "api-product-strategy", "user-experience", "market-insights", "business-goals", "competitive-analysis", "ecosystem-vision" ] }, { "id": "platform-architecture-line", "slug": "platform-architecture-line", "title": "Linha de arquitetura da plataforma", "description": "Abrange os aspetos arquiteturais das plataformas API.", "icon": "", "color": "#933469", "order": 2, "stations": [ "api-product-strategy", "api-consumer-experience", "api-platform-architecture", "scalable-infrastructure", "legal-and-compliance", "security-and-privacy", "design-standards", "vendor-management" ] }, { "id": "api-design-line", "slug": "api-design-line", "title": "Linha de conceção de API", "description": "Centra-se nos princípios e práticas de conceção de APIs.", "icon": "", "color": "#db9b0c", "order": 3, "stations": [ "api-platform-architecture", "api-design", "api-delivery", "api-audit" ] }, { "id": "delivery-line", "slug": "delivery-line", "title": "Linha de entrega", "description": "Abrange os processos e práticas de entrega de APIs.", "icon": "", "color": "#db9b0c", "order": 4, "stations": [ "api-delivery", "contract-design", "development", "ci-cd", "test-automation", "release-management" ] }, { "id": "publishing-and-adoption-line", "slug": "publishing-and-adoption-line", "title": "Linha de publicação e adoção", "description": "Centra-se na publicação de APIs e na garantia da sua adoção pelos consumidores.", "icon": "", "color": "#17C6E9", "order": 5, "stations": [ "api-audit", "api-publishing", "monitoring-and-improving", "service-agreements", "api-consumer-adoption", "api-promotion", "partner-integration" ] }, { "id": "operating-model-line", "slug": "operating-model-line", "title": "Linha de modelo operacional", "description": "Abrange o modelo operacional para gestão e governação de API.", "icon": "", "color": "#1a3987", "order": 6, "stations": [ "api-product-strategy", "api-mindset", "roles-and-responsibilities", "upskilling", "operating-guidelines", "portfolio-management", "budget-and-resource-management" ] } ], "stations": [ { "id": "api-product-strategy", "slug": "method/api-product-strategy", "icon": "strategy-outline", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia.", "whyItMatters": "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais.", "applyInWork": "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "strategy", "outcomes": [ "Uma proposta de valor e um público-alvo da API simples", "Linguagem partilhada entre o produto, a conceção e a tecnologia", "Um argumento sólido ou um caso para financiamento/aprovação" ], "steps": [ { "text": "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas" }, { "text": "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas" }, { "text": "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas" }, { "text": "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "resourceId": "apiBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da API", "canvasId": "apiBusinessModelCanvas" } ], "questions": [ "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais." ], "criteria": [ "metrics-feedback-available", "business-goals-defined", "market-research-done", "stakeholder-approval" ], "criteriaDetails": [ { "id": "metrics-feedback-available", "title": "Sinais de mercado relevantes, feedback ou conhecimento operacional estão disponíveis para orientar esta oportunidade de capacidade.", "description": "Relevant market signals, feedback, or operational insights are available to guide this API opportunity." }, { "id": "business-goals-defined", "title": "Os objetivos de negócio estão definidos.", "description": "Business goals are defined." }, { "id": "market-research-done", "title": "A investigação de mercado identifica oportunidades de capacidade.", "description": "Market research identifies API opportunities." }, { "id": "stakeholder-approval", "title": "As partes interessadas relevantes concordam que vale a pena explorar e priorizar esta oportunidade de capacidade.", "description": "Relevant stakeholders agree this API opportunity is worth exploring and prioritizing." } ], "stakeholders": [ { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "lead", "responsibilities": [] }, { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "lead", "responsibilities": [] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "lead", "responsibilities": [ { "resourceId": "capabilityValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da Capacidade", "canvasId": "capabilityValuePropositionCanvas", "role": "suggested-answer-owner" }, { "resourceId": "capabilityBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da Capacidade", "canvasId": "capabilityBusinessModelCanvas", "role": "suggested-answer-owner" } ] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "lead", "responsibilities": [ { "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas", "role": "suggested-answer-owner" }, { "resourceId": "apiBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da API", "canvasId": "apiBusinessModelCanvas", "role": "suggested-answer-owner" } ] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [ { "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas", "role": "suggested-answer-owner" } ] }, { "id": "customer-specialist", "sourceKey": "customer-specialist", "sourceStakeholderId": "customer-specialist", "title": "Representante de cliente ou parceiro", "description": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "involvement": "core", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [ { "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas", "role": "suggested-answer-owner" } ] }, { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "core", "responsibilities": [] }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "consulted", "responsibilities": [] }, { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "consulted", "responsibilities": [] }, { "id": "partner-specialist", "sourceKey": "partner-specialist", "sourceStakeholderId": "partner-specialist", "title": "Gestor de parceiros ou fornecedores", "description": "Coordena relações com parceiros, fornecedores ou prestadores externos que influenciam a estratégia e entrega da capacidade ou API.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-program-owner", "sourceKey": "api-program-owner", "sourceStakeholderId": "api-program-owner", "title": "Responsável pelo programa API", "description": "Coordena as práticas do portefólio de APIs, o alinhamento organizacional e o desenvolvimento de capacidades API a longo prazo.", "involvement": "consulted", "responsibilities": [] } ], "evidence": [ "design-artifact", "documentation", "research", "roadmap" ] }, { "id": "user-experience", "slug": "method/user-experience", "icon": "user-attributes-outline", "title": "Experiência do utilizador - Conceber APIs com o utilizador em mente", "description": "Assegurar que as APIs são concebidas tendo em mente o utilizador final, proporcionando uma experiência intuitiva e sem descontinuidades.", "whyItMatters": "As APIs não são apenas produtos técnicos; são produtos virados para o utilizador. Uma má experiência do utilizador pode levar a uma baixa adoção e à frustração. Esta estação ajuda as equipas a conceber APIs que sejam fáceis de utilizar e que satisfaçam as necessidades dos consumidores.", "applyInWork": "Fornecer orientações, modelos e ferramentas de experiência do utilizador para a conceção de API. Assegurar que as equipas seguem práticas de design centradas no utilizador e incorporam o feedback do utilizador nas iterações da API.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "APIs concebidas a pensar nas necessidades dos utilizadores", "Interfaces de utilizador intuitivas e coerentes", "Feedback do utilizador incorporado na conceção da API", "Maior satisfação e adoção por parte dos utilizadores" ], "steps": [ { "text": "Utilizar as personas dos utilizadores para compreender as necessidades e expectativas dos utilizadores finais", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas" }, { "text": "Realize estudos de utilizadores para obter informações sobre a forma como os consumidores interagem com os serviços do ecossistema ou com as suas aplicações que consomem API.", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas" }, { "text": "Documentar os requisitos da experiência do utilizador para que possam ser utilizados na conceção da API, garantindo que são intuitivos e fáceis de utilizar.", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas" } ], "questions": [ "Utilizar as personas dos utilizadores para compreender as necessidades e expectativas dos utilizadores finais", "Realize estudos de utilizadores para obter informações sobre a forma como os consumidores interagem com os serviços do ecossistema ou com as suas aplicações que consomem API.", "Documentar os requisitos da experiência do utilizador para que possam ser utilizados na conceção da API, garantindo que são intuitivos e fáceis de utilizar.", "Fornecer orientações, modelos e ferramentas de experiência do utilizador para a conceção de API. Assegurar que as equipas seguem práticas de design centradas no utilizador e incorporam o feedback do utilizador nas iterações da API.", "As APIs não são apenas produtos técnicos; são produtos virados para o utilizador. Uma má experiência do utilizador pode levar a uma baixa adoção e à frustração. Esta estação ajuda as equipas a conceber APIs que sejam fáceis de utilizar e que satisfaçam as necessidades dos consumidores." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "api-consumer-experience", "slug": "method/api-consumer-experience", "icon": "deployed-code-account-outline", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento.", "whyItMatters": "As APIs excelentes não funcionam apenas - elas são intuitivas. Quer o consumidor seja um programador interno, um parceiro externo ou um agente de IA, a sua experiência determina a adoção.\n\nSnum plano de experiência claro:\n- Grandes APIs ficam sem uso\n- As equipas perdem tempo a tentar adivinhar como utilizar a sua API\n- Os ciclos de feedback estão quebrados ou ausentes.\n\nEsta estação ajuda-o a ver a sua API através dos olhos dos seus consumidores.", "applyInWork": "Fornecer diretrizes, ferramentas e mecanismos de feedback para compreender, analisar e melhorar a experiência interna e externa dos programadores e parceiros.", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "strategy", "outcomes": [ "Identifique e dê prioridade aos seus consumidores de API", "Definir o percurso da experiência API", "Planeamento da integração, documentação e feedback", "Melhorar a adoção através de empatia genuína + Experiência do Programador (DX)" ], "steps": [ { "text": "Analise o Canvas da Proposta de Valor da API existente sob a perspectiva do consumidor da API. Mantenha as tarefas de negócios suportadas estáveis ​​e enriqueça os recursos que aliviam problemas e possibilitam ganhos com as preocupações do consumidor da API, para que elas possam orientar as decisões de conceção futuras.", "resourceId": "apiValuePropositionCanvas", "resourceTitle": "Canvas da Proposta de Valor da API", "canvasId": "apiValuePropositionCanvas" }, { "text": "Utilize o Canvas do Percurso do Cliente para a jornada do consumidor da API, desde a descoberta e avaliação até a integração, resolução de problemas e uso contínuo.", "resourceId": "customerJourneyCanvas", "resourceTitle": "Canvas do Percurso do Cliente", "canvasId": "customerJourneyCanvas" }, { "text": "Utilize a jornada resultante para melhorar a integração, a documentação, o suporte e os ciclos de feedback para o consumidor da API.", "resourceId": "api-onboarding-best-practices", "resourceTitle": "Boas práticas de integração de API", "canvasId": null } ], "questions": [ "Analise o Canvas da Proposta de Valor da API existente sob a perspectiva do consumidor da API. Mantenha as tarefas de negócios suportadas estáveis ​​e enriqueça os recursos que aliviam problemas e possibilitam ganhos com as preocupações do consumidor da API, para que elas possam orientar as decisões de conceção futuras.", "Utilize o Canvas do Percurso do Cliente para a jornada do consumidor da API, desde a descoberta e avaliação até a integração, resolução de problemas e uso contínuo.", "Utilize a jornada resultante para melhorar a integração, a documentação, o suporte e os ciclos de feedback para o consumidor da API.", "Fornecer diretrizes, ferramentas e mecanismos de feedback para compreender, analisar e melhorar a experiência interna e externa dos programadores e parceiros.", "As APIs excelentes não funcionam apenas - elas são intuitivas. Quer o consumidor seja um programador interno, um parceiro externo ou um agente de IA, a sua experiência determina a adoção.\n\nSnum plano de experiência claro:\n- Grandes APIs ficam sem uso\n- As equipas perdem tempo a tentar adivinhar como utilizar a sua API\n- Os ciclos de feedback estão quebrados ou ausentes.\n\nEsta estação ajuda-o a ver a sua API através dos olhos dos seus consumidores." ], "criteria": [ "api-opportunity-documented", "api-reusability", "hide-backend-discrepancies", "value-prop-validated", "consumer-segments-identified", "api-roadmap-defined" ], "criteriaDetails": [ { "id": "api-opportunity-documented", "title": "A oportunidade de capacidade está identificada e documentada.", "description": "Individual API opportunities are identified and documented." }, { "id": "api-reusability", "title": "A capacidade responde a uma necessidade clara de negócio e é reutilizável pelos utilizadores previstos.", "description": "The API meets a clear business need and is reusable for multiple API consumers." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "value-prop-validated", "title": "A proposta de valor da capacidade foi validada com partes interessadas de negócio e utilizadores.", "description": "The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders." }, { "id": "consumer-segments-identified", "title": "Os segmentos de utilizadores estão identificados.", "description": "API consumer segments (internal and external) are identified." }, { "id": "api-roadmap-defined", "title": "Está definido um roadmap de implementação de alto nível.", "description": "High-level roadmaps for API development are established." } ], "stakeholders": [ { "id": "customer-specialist", "sourceKey": "customer-specialist", "sourceStakeholderId": "customer-specialist", "title": "Representante de cliente ou parceiro", "description": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "involvement": "lead", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "lead", "responsibilities": [ { "resourceId": "consumerExperienceRequirementsCanvas", "resourceTitle": "Canvas de Requisitos da Experiência do Utilizador", "canvasId": "consumerExperienceRequirementsCanvas", "role": "suggested-answer-owner" } ] }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "lead", "responsibilities": [] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "lead", "responsibilities": [] }, { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "core", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [] }, { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "core", "responsibilities": [] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "core", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "core", "responsibilities": [] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "partner-specialist", "sourceKey": "partner-specialist", "sourceStakeholderId": "partner-specialist", "title": "Gestor de parceiros ou fornecedores", "description": "Coordena relações com parceiros, fornecedores ou prestadores externos que influenciam a estratégia e entrega da capacidade ou API.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "evidence": [ "design-artifact", "documentation", "consumer-feedback" ] }, { "id": "market-insights", "slug": "method/market-insights", "icon": "area-chart-outline", "title": "Informações sobre o mercado - Compreender o cenário das API", "description": "Analisar as tendências do mercado, as APIs da concorrência e as normas da indústria para informar a estratégia de API.", "whyItMatters": "Compreender o panorama do mercado ajuda as equipas a identificar oportunidades, evitar armadilhas e alinhar as suas APIs com as normas da indústria. Esta estação fornece ferramentas para analisar as tendências do mercado e as ofertas dos concorrentes.", "applyInWork": "Fornecer ferramentas de pesquisa de mercado, modelos de análise da concorrência e recursos de normas do sector. Assegurar que as equipas se mantêm informadas sobre as tendências do mercado e incorporam os conhecimentos na estratégia de API.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Análise das tendências do mercado e das APIs dos concorrentes", "Identificação das normas e boas práticas do sector", "Estratégia de API alinhada com as necessidades do mercado", "Tomada de decisões informadas com base em conhecimentos do mercado" ], "steps": [ { "text": "Realizar estudos de mercado para identificar tendências, oportunidades e ameaças no panorama das APIs.", "resourceId": "ecosystem-vision-template", "resourceTitle": "Modelo de visão do ecossistema", "canvasId": null }, { "text": "Analisar as APIs da concorrência para compreender os seus pontos fortes, fracos e pontos de venda únicos.", "resourceId": "competitor-analysis-template", "resourceTitle": "Modelo de análise da concorrência", "canvasId": null }, { "text": "Identificar as normas e as boas práticas do sector para garantir que as APIs são competitivas e estão em conformidade.", "resourceId": "industry-standards-and-best-practices", "resourceTitle": "Normas e boas práticas do sector", "canvasId": null } ], "questions": [ "Realizar estudos de mercado para identificar tendências, oportunidades e ameaças no panorama das APIs.", "Analisar as APIs da concorrência para compreender os seus pontos fortes, fracos e pontos de venda únicos.", "Identificar as normas e as boas práticas do sector para garantir que as APIs são competitivas e estão em conformidade.", "Fornecer ferramentas de pesquisa de mercado, modelos de análise da concorrência e recursos de normas do sector. Assegurar que as equipas se mantêm informadas sobre as tendências do mercado e incorporam os conhecimentos na estratégia de API.", "Compreender o panorama do mercado ajuda as equipas a identificar oportunidades, evitar armadilhas e alinhar as suas APIs com as normas da indústria. Esta estação fornece ferramentas para analisar as tendências do mercado e as ofertas dos concorrentes." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "api-platform-architecture", "slug": "method/api-platform-architecture", "icon": "code-blocks-outline", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma.", "whyItMatters": "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência.", "applyInWork": "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "architecture", "outcomes": [ "Corte APIs redundantes e reduza os custos da plataforma de nuvem", "Implementar uma governação consistente snum forte controlo do topo para a base", "Conceção para reutilização interna e escalabilidade externa" ], "steps": [ { "text": "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas" }, { "text": "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas" }, { "text": "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas" }, { "text": "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "resourceId": "api-metrics-and-analytics", "resourceTitle": "Métricas e análise de API", "canvasId": null } ], "questions": [ "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência." ], "criteria": [ "api-reusability", "hide-backend-discrepancies", "value-prop-validated", "consumer-segments-identified", "api-roadmap-defined" ], "criteriaDetails": [ { "id": "api-reusability", "title": "A capacidade responde a uma necessidade clara de negócio e é reutilizável pelos utilizadores previstos.", "description": "The API meets a clear business need and is reusable for multiple API consumers." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "value-prop-validated", "title": "A proposta de valor da capacidade foi validada com partes interessadas de negócio e utilizadores.", "description": "The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders." }, { "id": "consumer-segments-identified", "title": "Os segmentos de utilizadores estão identificados.", "description": "API consumer segments (internal and external) are identified." }, { "id": "api-roadmap-defined", "title": "Está definido um roadmap de implementação de alto nível.", "description": "High-level roadmaps for API development are established." } ], "stakeholders": [ { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "lead", "responsibilities": [ { "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "role": "suggested-answer-owner" } ] }, { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "lead", "responsibilities": [] }, { "id": "api-architect", "sourceKey": "api-architect", "sourceStakeholderId": "api-architect", "title": "Arquiteto API", "description": "Responsável pela arquitetura API, pelos princípios de desenho e pela qualidade dos contratos de interface.", "involvement": "core", "responsibilities": [ { "resourceId": "locationsCanvas", "resourceTitle": "Canvas de Localização", "canvasId": "locationsCanvas", "role": "suggested-answer-owner" }, { "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas", "role": "suggested-answer-owner" } ] }, { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "core", "responsibilities": [ { "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas", "role": "suggested-answer-owner" } ] }, { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "core", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "core", "responsibilities": [] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "core", "responsibilities": [ { "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas", "role": "suggested-answer-owner" } ] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "core", "responsibilities": [ { "resourceId": "businessImpactCanvas", "resourceTitle": "Canvas de Impacto no Negócio", "canvasId": "businessImpactCanvas", "role": "suggested-answer-owner" } ] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "evidence": [ "architecture-decision", "documentation", "platform-config", "metrics" ] }, { "id": "business-goals", "slug": "method/business-goals", "icon": "business-center-outline", "title": "Objectivos comerciais - Alinhar as APIs com os objetivos de negócio", "description": "Assegurar que as APIs estão alinhadas com os objetivos de negócio e contribuem para os objetivos organizacionais globais.", "whyItMatters": "As APIs não devem ser construídas isoladamente; elas devem apoiar e impulsionar os objetivos de negócio. Esta estação ajuda as equipas a alinharem as suas APIs com os objetivos estratégicos, assegurando que fornecnum verdadeiro valor de negócio.", "applyInWork": "Fornecer estruturas, modelos e ferramentas de alinhamento comercial para definir o valor de negócio da API. Garantir que as equipas revejam e alinhem regularmente as APIs com os objetivos de negócio em mudança.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "APIs alinhadas com os objetivos de negócio", "Valor de negócio claro definido para cada API", "Adesão e apoio das partes interessadas às iniciativas API", "As APIs contribuem para o sucesso organizacional" ], "steps": [ { "text": "Definir os objetivos de negócio e a forma como as APIs podem apoiá-los utilizando **o Business Model Canvas**. Se o seu negócio é fornecer APIs, passe pela *estação de Estratégia de Produto de API* e preencha **o Modelo de Negócio de API Canvas**.", "resourceId": "apiBusinessModelCanvas", "resourceTitle": "Canvas do Modelo de Negócio da API", "canvasId": "apiBusinessModelCanvas" }, { "text": "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "resourceId": "api-metrics-and-analytics", "resourceTitle": "Métricas e análise de API", "canvasId": null }, { "text": "Envolver as partes interessadas para garantir o alinhamento e o apoio às iniciativas da API.", "resourceId": "stakeholder-engagement-best-practices", "resourceTitle": "Boas práticas de envolvimento das partes interessadas", "canvasId": null } ], "questions": [ "Definir os objetivos de negócio e a forma como as APIs podem apoiá-los utilizando **o Business Model Canvas**. Se o seu negócio é fornecer APIs, passe pela *estação de Estratégia de Produto de API* e preencha **o Modelo de Negócio de API Canvas**.", "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "Envolver as partes interessadas para garantir o alinhamento e o apoio às iniciativas da API.", "Fornecer estruturas, modelos e ferramentas de alinhamento comercial para definir o valor de negócio da API. Garantir que as equipas revejam e alinhem regularmente as APIs com os objetivos de negócio em mudança.", "As APIs não devem ser construídas isoladamente; elas devem apoiar e impulsionar os objetivos de negócio. Esta estação ajuda as equipas a alinharem as suas APIs com os objetivos estratégicos, assegurando que fornecnum verdadeiro valor de negócio." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "api-design", "slug": "method/api-design", "icon": "api", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados.", "whyItMatters": "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.", "applyInWork": "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.", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "design", "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": [ { "text": "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs.", "resourceId": "domainCanvas", "resourceTitle": "Canvas de Domínio", "canvasId": "domainCanvas" }, { "text": "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.", "resourceId": "interactionCanvas", "resourceTitle": "Canvas de Interação", "canvasId": "interactionCanvas" }, { "text": "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.", "resourceId": "restCanvas", "resourceTitle": "Canvas REST", "canvasId": "restCanvas" }, { "text": "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.", "resourceId": "eventCanvas", "resourceTitle": "Canvas de Eventos", "canvasId": "eventCanvas" }, { "text": "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.", "resourceId": "graphqlCanvas", "resourceTitle": "Canvas GraphQL", "canvasId": "graphqlCanvas" }, { "text": "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.", "resourceId": "api-design-principles", "resourceTitle": "Princípios de conceção da API", "canvasId": null }, { "text": "Aplique abordagens do tipo ‘contrato primeiro’ ou ‘design primeiro’ para capturar e validar o contrato de interface da API antes da implementação.", "resourceId": "contract-first-design", "resourceTitle": "Primeira conceção do contrato", "canvasId": null }, { "text": "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.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "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." ], "criteria": [ "architecture-patterns-validated", "hide-backend-discrepancies", "design-reflects-business-value", "api-consistency" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." } ], "stakeholders": [ { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "lead", "responsibilities": [] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "lead", "responsibilities": [] }, { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "lead", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "core", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "core", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [] }, { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "core", "responsibilities": [] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "core", "responsibilities": [] }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "core", "responsibilities": [] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "consulted", "responsibilities": [] } ], "evidence": [ "spec", "contract", "design-artifact", "documentation" ] }, { "id": "competitive-analysis", "slug": "method/competitive-analysis", "icon": "trophy-outline", "title": "Análise competitiva - Fique à frente no mercado de API", "description": "Analisar as APIs dos concorrentes para identificar pontos fortes, pontos fracos e oportunidades de diferenciação.", "whyItMatters": "Compreender o cenário competitivo ajuda as equipas a identificar lacunas, oportunidades e áreas de melhoria nas suas APIs. Esta estação fornece ferramentas para analisar os concorrentes e informar a estratégia de API.", "applyInWork": "Fornecer ferramentas, modelos e recursos de análise da concorrência. Assegurar que as equipas analisam regularmente os concorrentes e incorporam os conhecimentos na estratégia e conceção da API.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "APIs da concorrência analisadas quanto aos pontos fortes e fracos", "Identificação de oportunidades de diferenciação", "Estratégia de API baseada em informações sobre a concorrência", "Aumento da competitividade no mercado de API" ], "steps": [ { "text": "Efetuar uma análise da concorrência para identificar os principais concorrentes, as suas ofertas de API e os seus pontos fortes e fracos.", "resourceId": "competitor-analysis-template", "resourceTitle": "Modelo de análise da concorrência", "canvasId": null }, { "text": "Identifique as lacunas no mercado que as suas APIs podem preencher, com base nas ofertas da concorrência.", "resourceId": "ecosystem-vision-template", "resourceTitle": "Modelo de visão do ecossistema", "canvasId": null }, { "text": "Desenvolva uma estratégia de diferenciação que destaque as características e benefícios únicos das suas APIs.", "resourceId": "ecosystem-vision-template", "resourceTitle": "Modelo de visão do ecossistema", "canvasId": null } ], "questions": [ "Efetuar uma análise da concorrência para identificar os principais concorrentes, as suas ofertas de API e os seus pontos fortes e fracos.", "Identifique as lacunas no mercado que as suas APIs podem preencher, com base nas ofertas da concorrência.", "Desenvolva uma estratégia de diferenciação que destaque as características e benefícios únicos das suas APIs.", "Fornecer ferramentas, modelos e recursos de análise da concorrência. Assegurar que as equipas analisam regularmente os concorrentes e incorporam os conhecimentos na estratégia e conceção da API.", "Compreender o cenário competitivo ajuda as equipas a identificar lacunas, oportunidades e áreas de melhoria nas suas APIs. Esta estação fornece ferramentas para analisar os concorrentes e informar a estratégia de API." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "api-delivery", "slug": "method/api-delivery", "icon": "code", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia.", "whyItMatters": "Mesmo os melhores conceções de API falham se a entrega for inconsistente. Esta estação assegura que as suas APIs são construídas com qualidade, testadas exaustivamente e implementadas de forma fiável - permitindo iterações mais rápidas e maior confiança.", "applyInWork": "Fornecer estruturas de codificação, bibliotecas e normas para a implementação de API. Implementar pipelines de CI/CD, estruturas de garantia de qualidade e ferramentas de automatização da disponibilização.", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "delivery", "outcomes": [ "APIs implementadas utilizando estruturas e padrões testados", "Pipelines de CI/CD fiáveis e automatizados", "Testes funcionais e não funcionais integrados", "Condutas de entrega seguras e conformes" ], "steps": [ { "text": "Utilize as Melhores Práticas de Desenvolvimento de API como orientação para implementar o contrato validado com frameworks e bibliotecas estabelecidos, garantindo que o resultado seja reutilizável e sustentável.", "resourceId": "api-development-best-practices", "resourceTitle": "Boas práticas de desenvolvimento de API", "canvasId": null }, { "text": "Construa a implementação da API a partir do contrato validado usando frameworks, bibliotecas e padrões da equipa estabelecidos.", "resourceId": "api-development-best-practices", "resourceTitle": "Boas práticas de desenvolvimento de API", "canvasId": null }, { "text": "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "resourceId": "api-testing-best-practices", "resourceTitle": "Boas práticas de teste de API", "canvasId": null }, { "text": "Utilize pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null }, { "text": "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "resourceId": "api-security-best-practices", "resourceTitle": "Boas práticas de segurança da API", "canvasId": null }, { "text": "Utilize a lista de verificação de auditoria da API para garantir que a API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "questions": [ "Utilize as Melhores Práticas de Desenvolvimento de API como orientação para implementar o contrato validado com frameworks e bibliotecas estabelecidos, garantindo que o resultado seja reutilizável e sustentável.", "Construa a implementação da API a partir do contrato validado usando frameworks, bibliotecas e padrões da equipa estabelecidos.", "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Utilize pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "Utilize a lista de verificação de auditoria da API para garantir que a API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Fornecer estruturas de codificação, bibliotecas e normas para a implementação de API. Implementar pipelines de CI/CD, estruturas de garantia de qualidade e ferramentas de automatização da disponibilização.", "Mesmo os melhores conceções de API falham se a entrega for inconsistente. Esta estação assegura que as suas APIs são construídas com qualidade, testadas exaustivamente e implementadas de forma fiável - permitindo iterações mais rápidas e maior confiança." ], "criteria": [ "architecture-patterns-validated", "hide-backend-discrepancies", "design-reflects-business-value", "api-consistency" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." } ], "stakeholders": [ { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "lead", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "lead", "responsibilities": [] }, { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "core", "responsibilities": [] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "partner-specialist", "sourceKey": "partner-specialist", "sourceStakeholderId": "partner-specialist", "title": "Gestor de parceiros ou fornecedores", "description": "Coordena relações com parceiros, fornecedores ou prestadores externos que influenciam a estratégia e entrega da capacidade ou API.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "consulted", "responsibilities": [] }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "consulted", "responsibilities": [] } ], "evidence": [ "implementation", "pipeline-config", "test-report", "security-report" ] }, { "id": "ecosystem-vision", "slug": "method/ecosystem-vision", "icon": "globe-book-rounded", "title": "Visão do ecossistema - Criar APIs para um ecossistema próspero", "description": "Crie uma visão de como as suas APIs se encaixam num ecossistema maior, permitindo a colaboração e a inovação.", "whyItMatters": "As APIs não são produtos autónomos; fazem parte de um ecossistema maior. Esta estação ajuda as equipas a definir como as suas APIs interagem com outros sistemas, plataformas e serviços para criar um ecossistema próspero que promove a colaboração e a inovação.", "applyInWork": "Fornecer estruturas de visão do ecossistema, estratégias de envolvimento de parceiros e diretrizes de integração. Garantir que as equipas concebem APIs com o ecossistema em mente e promovem a colaboração entre parceiros.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Definição de uma visão clara do ecossistema para as API", "APIs concebidas para permitir a colaboração e a integração", "Parceiros do ecossistema identificados e envolvidos", "As APIs contribuem para um ecossistema dinâmico" ], "steps": [ { "text": "Defina a visão do ecossistema para as suas APIs, incluindo a forma como estas irão interagir com outros sistemas e plataformas.", "resourceId": "ecosystem-vision-template", "resourceTitle": "Modelo de visão do ecossistema", "canvasId": null }, { "text": "Identificar os principais parceiros e intervenientes do ecosistema que irão beneficiar ou contribuir para o ecosistema.", "resourceId": "ecosystem-vision-template", "resourceTitle": "Modelo de visão do ecossistema", "canvasId": null }, { "text": "Conceber APIs para permitir uma integração e colaboração perfeitas no ecossistema.", "resourceId": "ecosystem-vision-template", "resourceTitle": "Modelo de visão do ecossistema", "canvasId": null } ], "questions": [ "Defina a visão do ecossistema para as suas APIs, incluindo a forma como estas irão interagir com outros sistemas e plataformas.", "Identificar os principais parceiros e intervenientes do ecosistema que irão beneficiar ou contribuir para o ecosistema.", "Conceber APIs para permitir uma integração e colaboração perfeitas no ecossistema.", "Fornecer estruturas de visão do ecossistema, estratégias de envolvimento de parceiros e diretrizes de integração. Garantir que as equipas concebem APIs com o ecossistema em mente e promovem a colaboração entre parceiros.", "As APIs não são produtos autónomos; fazem parte de um ecossistema maior. Esta estação ajuda as equipas a definir como as suas APIs interagem com outros sistemas, plataformas e serviços para criar um ecossistema próspero que promove a colaboração e a inovação." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "api-audit", "slug": "method/api-audit", "icon": "check-box-outline", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição.", "whyItMatters": "As APIs são produtos de longa duração e devem atender às expectativas de qualidade, consistência e conformidade. A auditoria conecta as decisões de conceção, a implementação e a prontidão operacional a padrões definidos, reduzindo o risco antes da exposição.", "applyInWork": "Estabeleça um processo de auditoria consistente que avalie a prontidão da API em todas as etapas do ciclo de vida usando critérios, evidências e padrões definidos. Garanta que as lacunas sejam identificadas antecipadamente e resolvidas antes da publicação.", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "publishing", "outcomes": [ "As APIs cumprems normas internas e externas", "Documentação clara das decisões de conceção e implementação da API", "Segurança, desempenho e conformidade validados", "Redução do risco de problemas na produção" ], "steps": [ { "text": "Realizar auditorias para garantir que as APIs cumprems normas organizacionais, técnicas e legais antes da publicação.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null }, { "text": "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas.", "resourceId": "api-compliance-best-practices", "resourceTitle": "Boas práticas de conformidade da API", "canvasId": null }, { "text": "Colaborar com as equipas de governação e especialistas no domínio para garantir que as APIs estão prontas para produção.", "resourceTitle": "", "canvasId": null } ], "questions": [ "Realizar auditorias para garantir que as APIs cumprems normas organizacionais, técnicas e legais antes da publicação.", "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas.", "Colaborar com as equipas de governação e especialistas no domínio para garantir que as APIs estão prontas para produção.", "Estabeleça um processo de auditoria consistente que avalie a prontidão da API em todas as etapas do ciclo de vida usando critérios, evidências e padrões definidos. Garanta que as lacunas sejam identificadas antecipadamente e resolvidas antes da publicação.", "As APIs são produtos de longa duração e devem atender às expectativas de qualidade, consistência e conformidade. A auditoria conecta as decisões de conceção, a implementação e a prontidão operacional a padrões definidos, reduzindo o risco antes da exposição." ], "criteria": [ "architecture-patterns-validated", "design-reflects-business-value", "api-description-available", "api-consistency", "api-contract-tested" ], "criteriaDetails": [ { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders." }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs." }, { "id": "api-description-available", "title": "A interface e as suas capacidades estão documentadas de forma suficientemente clara para revisão, auditoria e onboarding.", "description": "The API and its exposed capabilities are described clearly enough for review, audit, and onboarding." }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions." }, { "id": "api-contract-tested", "title": "O contrato de interface foi validado e testado face aos requisitos funcionais e não funcionais.", "description": "The API contract is tested and meets functional and non-functional requirements." } ], "stakeholders": [ { "id": "governance-specialist", "sourceKey": "governance-specialist", "sourceStakeholderId": "governance-specialist", "title": "Responsável pela governação API", "description": "Representa práticas de revisão, auditoria e governação em toda a organização para qualidade e conformidade das APIs.", "involvement": "lead", "responsibilities": [] }, { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "core", "responsibilities": [] }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "core", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "core", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "core", "responsibilities": [] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "core", "responsibilities": [] }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "consulted", "responsibilities": [] }, { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "consulted", "responsibilities": [] } ], "evidence": [ "audit-report", "compliance-report", "security-report", "test-report" ] }, { "id": "scalable-infrastructure", "slug": "method/scalable-infrastructure", "icon": "cloud-done-outline", "title": "Infraestrutura escalável - Construir APIs sobre uma base sólida", "description": "Certifique-se de que a sua infraestrutura de API pode ser dimensionada para responder à crescente procura e suportar uma elevada disponibilidade.", "whyItMatters": "As APIs devem ser construídas numa infraestrutura robusta que possa lidar com o aumento do tráfego e garantir uma elevada disponibilidade. Esta estação fornece diretrizes para a conceção e implementação de uma infraestrutura escalável que suporte o crescimento e o desempenho da API.", "applyInWork": "Fornecer diretrizes de conceção de infra-estruturas, padrões nativos da nuvem e ferramentas de monitorização. Assegurar que as equipas implementam uma infraestrutura escalável que se pode adaptar às exigências em mudança e suportar o desempenho da API.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Infraestrutura API escalável e resiliente", "Elevada disponibilidade e desempenho sob carga", "Infra-estruturas concebidas para o crescimento futuro", "Redução do tempo de inatividade e melhoria da experiência do utilizador" ], "steps": [ { "text": "Conceber a infraestrutura da API para ser escalável e resiliente, utilizando padrões e tecnologias nativos da nuvem.", "resourceId": "scalable-infrastructure-best-practices", "resourceTitle": "Boas práticas de infraestrutura escalável", "canvasId": null }, { "text": "Implementar o equilíbrio de carga, o armazenamento em cache e outras técnicas para garantir uma elevada disponibilidade e desempenho. Recolher os requisitos de infraestrutura das equipas de API utilizando o Canvas de Capacidade", "resourceId": "capacityCanvas", "resourceTitle": "Canvas de Capacidade", "canvasId": "capacityCanvas" }, { "text": "Monitorizar o desempenho e a capacidade da infraestrutura para garantir que esta consegue dar resposta à crescente procura.", "resourceId": "scalable-infrastructure-best-practices", "resourceTitle": "Boas práticas de infraestrutura escalável", "canvasId": null } ], "questions": [ "Conceber a infraestrutura da API para ser escalável e resiliente, utilizando padrões e tecnologias nativos da nuvem.", "Implementar o equilíbrio de carga, o armazenamento em cache e outras técnicas para garantir uma elevada disponibilidade e desempenho. Recolher os requisitos de infraestrutura das equipas de API utilizando o Canvas de Capacidade", "Monitorizar o desempenho e a capacidade da infraestrutura para garantir que esta consegue dar resposta à crescente procura.", "Fornecer diretrizes de conceção de infra-estruturas, padrões nativos da nuvem e ferramentas de monitorização. Assegurar que as equipas implementam uma infraestrutura escalável que se pode adaptar às exigências em mudança e suportar o desempenho da API.", "As APIs devem ser construídas numa infraestrutura robusta que possa lidar com o aumento do tráfego e garantir uma elevada disponibilidade. Esta estação fornece diretrizes para a conceção e implementação de uma infraestrutura escalável que suporte o crescimento e o desempenho da API." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "api-publishing", "slug": "method/api-publishing", "icon": "deployed-code-outline", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos.", "whyItMatters": "A publicação é mais do que a disponibilização - trata-se de capacidade de descoberta, acesso e suporte. Se as APIs não forem publicadas corretamente, não serão utilizadas, reutilizadas ou protegidas de forma eficaz.", "applyInWork": "Permitir que as APIs sejam publicadas no ambiente relevante e ter mecanismos claros de registo e acesso (por exemplo, chaves de API, OAuth, planos de subscrição), dependendo dos segmentos de consumidores de API e dos requisitos de segurança e conformidade.", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "publishing", "outcomes": [ "APIs publicadas no ambiente correto (privado, parceiro, público)", "Processos claros de integração e registo da API", "Documentação, modelos e políticas de segurança disponíveis", "APIs prontas para escala e governação" ], "steps": [ { "text": "Publicar APIs nos gateways e ambientes adequados para apoiar a reutilização por vários consumidores de API.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null }, { "text": "Documentar a forma como os consumidores encontram e utilizam a API, incluindo processos de integração e registo.", "resourceId": "api-onboarding-best-practices", "resourceTitle": "Boas práticas de integração de API", "canvasId": null }, { "text": "Garantir que os modelos de segurança, a configuração da porta de ligação e os termos legais sejam claros e acessíveis aos consumidores.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "questions": [ "Publicar APIs nos gateways e ambientes adequados para apoiar a reutilização por vários consumidores de API.", "Documentar a forma como os consumidores encontram e utilizam a API, incluindo processos de integração e registo.", "Garantir que os modelos de segurança, a configuração da porta de ligação e os termos legais sejam claros e acessíveis aos consumidores.", "Permitir que as APIs sejam publicadas no ambiente relevante e ter mecanismos claros de registo e acesso (por exemplo, chaves de API, OAuth, planos de subscrição), dependendo dos segmentos de consumidores de API e dos requisitos de segurança e conformidade.", "A publicação é mais do que a disponibilização - trata-se de capacidade de descoberta, acesso e suporte. Se as APIs não forem publicadas corretamente, não serão utilizadas, reutilizadas ou protegidas de forma eficaz." ], "criteria": [ "audit-passed", "audit-reports-shared", "api-ready-for-publishing", "api-documentation-ready" ], "criteriaDetails": [ { "id": "audit-passed", "title": "A solução passa as verificações de qualidade, segurança, conformidade e prontidão.", "description": "The API passes compliance, security, and audit checks." }, { "id": "audit-reports-shared", "title": "As conclusões da auditoria e as decisões de correção são partilhadas com as partes interessadas relevantes.", "description": "Audit findings and remediation decisions are shared with the relevant stakeholders." }, { "id": "api-ready-for-publishing", "title": "A capacidade está pronta para ser publicada ou disponibilizada através do mecanismo de entrega selecionado.", "description": "The API is ready to be deployed and exposed through the intended gateways and environments." }, { "id": "api-documentation-ready", "title": "A documentação orientada para os utilizadores e os materiais de onboarding estão prontos.", "description": "Consumer-facing API documentation is complete enough for publishing and onboarding." } ], "stakeholders": [ { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "lead", "responsibilities": [] }, { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "lead", "responsibilities": [] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "lead", "responsibilities": [] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "lead", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "core", "responsibilities": [] }, { "id": "partner-specialist", "sourceKey": "partner-specialist", "sourceStakeholderId": "partner-specialist", "title": "Gestor de parceiros ou fornecedores", "description": "Coordena relações com parceiros, fornecedores ou prestadores externos que influenciam a estratégia e entrega da capacidade ou API.", "involvement": "core", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [] }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "core", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "consulted", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "consulted", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "consulted", "responsibilities": [] } ], "evidence": [ "gateway-config", "developer-portal", "documentation", "release-record" ] }, { "id": "legal-and-compliance", "slug": "method/legal-and-compliance", "icon": "gavel-rounded", "title": "Legal e Conformidade - Garantir que as APIs cumprems normas regulamentares", "description": "Garanta que as APIs cumprem os requisitos legais e regulamentares, protegendo a sua organização e os seus utilizadores.", "whyItMatters": "As APIs devem cumprir as normas legais e regulamentares para proteger a sua organização e os utilizadores. Esta estação fornece ferramentas e diretrizes para garantir que as APIs cumprem os requisitos de conformidade, reduzindo os riscos legais e garantindo a proteção de dados.", "applyInWork": "Fornecer estruturas legais e de conformidade, listas de verificação e ferramentas para garantir a conformidade da API. Assegurar que as equipas compreendem e implementam os requisitos legais na conceção, desenvolvimento e publicação de API.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "APIs em conformidade com as normas legais e regulamentares", "Cumprimento dos requisitos de proteção de dados e privacidade", "Riscos jurídicos identificados e atenuados", "Documentação clara das medidas de conformidade" ], "steps": [ { "text": "Identifique os requisitos legais e regulamentares que se aplicam às suas APIs, tais como proteção de dados, privacidade e normas de segurança.", "resourceId": "api-compliance-best-practices", "resourceTitle": "Boas práticas de conformidade da API", "canvasId": null }, { "text": "Implementar medidas para garantir que as APIs cumprem estes requisitos, incluindo encriptação de dados, controlos de acesso e pistas de auditoria.", "resourceId": "api-compliance-best-practices", "resourceTitle": "Boas práticas de conformidade da API", "canvasId": null }, { "text": "Documentar as medidas de conformidade e garantir que são comunicadas às partes interessadas e aos consumidores.", "resourceId": "api-compliance-best-practices", "resourceTitle": "Boas práticas de conformidade da API", "canvasId": null } ], "questions": [ "Identifique os requisitos legais e regulamentares que se aplicam às suas APIs, tais como proteção de dados, privacidade e normas de segurança.", "Implementar medidas para garantir que as APIs cumprem estes requisitos, incluindo encriptação de dados, controlos de acesso e pistas de auditoria.", "Documentar as medidas de conformidade e garantir que são comunicadas às partes interessadas e aos consumidores.", "Fornecer estruturas legais e de conformidade, listas de verificação e ferramentas para garantir a conformidade da API. Assegurar que as equipas compreendem e implementam os requisitos legais na conceção, desenvolvimento e publicação de API.", "As APIs devem cumprir as normas legais e regulamentares para proteger a sua organização e os utilizadores. Esta estação fornece ferramentas e diretrizes para garantir que as APIs cumprem os requisitos de conformidade, reduzindo os riscos legais e garantindo a proteção de dados." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "monitoring-and-improving", "slug": "method/monitoring-and-improving", "icon": "analytics-outline", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua.", "whyItMatters": "A entrega da API não pára no lançamento. Sem monitorização, as equipas não podem melhorar a adoção, o desempenho ou o ROI. Esta estação garante que as APIs permaneçam úteis, seguras e evoluindo com as necessidades do negócio.", "applyInWork": "Criar quadros analíticos para acompanhar o desempenho e o envolvimento. Desenvolver ciclos de feedback, ferramentas de análise e estratégias de envolvimento para APIs.", "group": "Estações centrais do ciclo de vida da API", "lifecycleStage": "improving", "outcomes": [ "Métricas de desempenho e utilização definidas e controladas", "Ciclos de feedback do programador em vigor", "Questões identificadas e tratadas continuamente", "Iteração da API alinhada com as necessidades dos utilizadores" ], "steps": [ { "text": "Monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "resourceId": "api-metrics-and-analytics", "resourceTitle": "Métricas e análise de API", "canvasId": null }, { "text": "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API.", "resourceId": "api-community-engagement-strategies", "resourceTitle": "Estratégias de envolvimento da comunidade API", "canvasId": null }, { "text": "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null } ], "questions": [ "Monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua.", "Criar quadros analíticos para acompanhar o desempenho e o envolvimento. Desenvolver ciclos de feedback, ferramentas de análise e estratégias de envolvimento para APIs.", "A entrega da API não pára no lançamento. Sem monitorização, as equipas não podem melhorar a adoção, o desempenho ou o ROI. Esta estação garante que as APIs permaneçam úteis, seguras e evoluindo com as necessidades do negócio." ], "criteria": [ "api-documentation-ready", "consumer-support-ready", "legal-compliance-clear" ], "criteriaDetails": [ { "id": "api-documentation-ready", "title": "A documentação orientada para os utilizadores e os materiais de onboarding estão prontos.", "description": "Consumer-facing API documentation is complete enough for publishing and onboarding." }, { "id": "consumer-support-ready", "title": "Os processos de onboarding, suporte e comunicação para utilizadores estão prontos.", "description": "Registration, support, and communication processes are ready for API consumers." }, { "id": "legal-compliance-clear", "title": "Os requisitos legais, de privacidade e de conformidade para publicação ou disponibilização estão definidos e compreendidos.", "description": "Legal, privacy, and compliance requirements for publishing are defined and understood." } ], "stakeholders": [ { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "lead", "responsibilities": [] }, { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "lead", "responsibilities": [] }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "lead", "responsibilities": [] }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "lead", "responsibilities": [] }, { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "core", "responsibilities": [] }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "core", "responsibilities": [] }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "core", "responsibilities": [] }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "core", "responsibilities": [] }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "core", "responsibilities": [] }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "core", "responsibilities": [] }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "core", "responsibilities": [] }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "consulted", "responsibilities": [] }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "consulted", "responsibilities": [] }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "consulted", "responsibilities": [] }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "consulted", "responsibilities": [] } ], "evidence": [ "metrics", "consumer-feedback", "incident-report", "roadmap" ] }, { "id": "security-and-privacy", "slug": "method/security-and-privacy", "icon": "cloud-lock-outline", "title": "Segurança e privacidade - Proteja as suas APIs e os seus utilizadores", "description": "Implementar medidas de segurança e privacidade para proteger as APIs e os dados dos utilizadores contra ameaças e violações.", "whyItMatters": "As APIs são vulneráveis a ameaças de segurança e violações de dados. Esta estação fornece orientações para a implementação de medidas de segurança e privacidade que protegem as APIs e os dados dos utilizadores, garantindo a confiança e a conformidade.", "applyInWork": "Fornecer estruturas de segurança, ferramentas e boas práticas para a segurança e privacidade da API. Assegurar que as equipas implementam medidas de segurança em todo o ciclo de vida da API, desde a conceção até à publicação e monitorização.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "APIs protegidas contra ameaças e vulnerabilidades", "Dados do utilizador protegidos através de medidas de privacidade", "Boas práticas de segurança implementadas na conceção e desenvolvimento de API", "Conformidade com as normas e regulamentos de segurança" ], "steps": [ { "text": "Implemente medidas de segurança como autenticação, autorização, encriptação e limitação de taxas para proteger as APIs de ameaças.", "resourceId": "api-security-best-practices", "resourceTitle": "Boas práticas de segurança da API", "canvasId": null }, { "text": "Garantir a privacidade dos dados dos utilizadores através da implementação de medidas de proteção de dados, como a anonimização e os controlos de acesso.", "resourceId": "data-privacy-guidelines", "resourceTitle": "Diretrizes de privacidade de dados", "canvasId": null }, { "text": "Efetuar auditorias de segurança regulares e avaliações de vulnerabilidade para identificar e atenuar os riscos.", "resourceId": "", "resourceTitle": "", "canvasId": null } ], "questions": [ "Implemente medidas de segurança como autenticação, autorização, encriptação e limitação de taxas para proteger as APIs de ameaças.", "Garantir a privacidade dos dados dos utilizadores através da implementação de medidas de proteção de dados, como a anonimização e os controlos de acesso.", "Efetuar auditorias de segurança regulares e avaliações de vulnerabilidade para identificar e atenuar os riscos.", "Fornecer estruturas de segurança, ferramentas e boas práticas para a segurança e privacidade da API. Assegurar que as equipas implementam medidas de segurança em todo o ciclo de vida da API, desde a conceção até à publicação e monitorização.", "As APIs são vulneráveis a ameaças de segurança e violações de dados. Esta estação fornece orientações para a implementação de medidas de segurança e privacidade que protegem as APIs e os dados dos utilizadores, garantindo a confiança e a conformidade." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "design-standards", "slug": "method/design-standards", "icon": "design-services-outline", "title": "Normas de conceção - Garantir uma conceção de API consistente e de alta qualidade", "description": "Estabelecer normas e diretrizes de design para garantir um design API consistente e de alta qualidade em toda a organização.", "whyItMatters": "Um conceção de API consistente e de alta qualidade é essencial para a usabilidade, manutenção e escalabilidade. Esta estação fornece normas e diretrizes de design que ajudam as equipas a criar APIs que são fáceis de utilizar, compreender e manter.", "applyInWork": "Fornecer documentação sobre normas de conceção, componentes reutilizáveis e processos de revisão da conceção. Assegurar que as equipas seguem as normas de conceção e realizam revisões regulares para manter uma conceção de API de alta qualidade.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Conceção consistente da API em toda a organização", "APIs de alta qualidade que satisfazem as necessidades dos utilizadores", "Componentes e padrões de conceção reutilizáveis", "Redução das inconsistências de conceção e da dívida técnica" ], "steps": [ { "text": "Definir normas e diretrizes de conceção para a conceção de API, incluindo convenções de nomenclatura, formatos de resposta e tratamento de erros.", "resourceId": "api-design-principles", "resourceTitle": "Princípios de conceção da API", "canvasId": null }, { "text": "Criar padrões de conceção e componentes reutilizáveis que as equipas possam utilizar para garantir a consistência e a qualidade.", "resourceId": "", "resourceTitle": "", "canvasId": null }, { "text": "Efetuar revisões e auditorias de conceção para garantir o cumprimento das normas de conceção e identificar áreas a melhorar.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "questions": [ "Definir normas e diretrizes de conceção para a conceção de API, incluindo convenções de nomenclatura, formatos de resposta e tratamento de erros.", "Criar padrões de conceção e componentes reutilizáveis que as equipas possam utilizar para garantir a consistência e a qualidade.", "Efetuar revisões e auditorias de conceção para garantir o cumprimento das normas de conceção e identificar áreas a melhorar.", "Fornecer documentação sobre normas de conceção, componentes reutilizáveis e processos de revisão da conceção. Assegurar que as equipas seguem as normas de conceção e realizam revisões regulares para manter uma conceção de API de alta qualidade.", "Um conceção de API consistente e de alta qualidade é essencial para a usabilidade, manutenção e escalabilidade. Esta estação fornece normas e diretrizes de design que ajudam as equipas a criar APIs que são fáceis de utilizar, compreender e manter." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "vendor-management", "slug": "method/vendor-management", "icon": "handshake-outline", "title": "Gestão de fornecedores - Gerir integrações de APIs de terceiros", "description": "Gerir eficazmente os fornecedores e as integrações de API de terceiros para garantir a fiabilidade e a conformidade.", "whyItMatters": "As APIs de terceiros podem introduzir riscos e dependências que afectam o seu ecossistema de API. Esta estação fornece diretrizes para gerir as relações com os fornecedores, garantindo a fiabilidade, a conformidade e o alinhamento com a sua estratégia de API.", "applyInWork": "Fornecer estruturas de gestão de fornecedores, critérios de avaliação e ferramentas de monitorização. Assegurar que as equipas gerem eficazmente os fornecedores de API de terceiros, garantindo a fiabilidade, a conformidade e o alinhamento com as normas organizacionais.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Estabelecimento de processos eficazes de gestão de fornecedores", "APIs de terceiros integradas de forma fiável e segura", "Conformidade do fornecedor com as normas organizacionais", "Redução dos riscos associados a dependências de terceiros" ], "steps": [ { "text": "Estabelecer processos de gestão de fornecedores para avaliar, integrar e monitorizar fornecedores de API de terceiros.", "resourceId": "vendor-management-best-practices", "resourceTitle": "Boas práticas de gestão de fornecedores", "canvasId": null }, { "text": "Definir critérios para avaliar as APIs dos fornecedores, incluindo fiabilidade, segurança e conformidade.", "resourceId": "vendor-management-best-practices", "resourceTitle": "Boas práticas de gestão de fornecedores", "canvasId": null }, { "text": "Monitorizar o desempenho dos fornecedores e o cumprimento dos acordos de nível de serviço (SLA) e das normas organizacionais.", "resourceId": "vendor-management-best-practices", "resourceTitle": "Boas práticas de gestão de fornecedores", "canvasId": null } ], "questions": [ "Estabelecer processos de gestão de fornecedores para avaliar, integrar e monitorizar fornecedores de API de terceiros.", "Definir critérios para avaliar as APIs dos fornecedores, incluindo fiabilidade, segurança e conformidade.", "Monitorizar o desempenho dos fornecedores e o cumprimento dos acordos de nível de serviço (SLA) e das normas organizacionais.", "Fornecer estruturas de gestão de fornecedores, critérios de avaliação e ferramentas de monitorização. Assegurar que as equipas gerem eficazmente os fornecedores de API de terceiros, garantindo a fiabilidade, a conformidade e o alinhamento com as normas organizacionais.", "As APIs de terceiros podem introduzir riscos e dependências que afectam o seu ecossistema de API. Esta estação fornece diretrizes para gerir as relações com os fornecedores, garantindo a fiabilidade, a conformidade e o alinhamento com a sua estratégia de API." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "contract-design", "slug": "method/contract-design", "icon": "folder-code-outline", "title": "Conceção de contratos - Definir contratos de interface da API claros", "description": "Criar contratos de interface da API claros e bem definidos que descrevam as expectativas, responsabilidades e diretrizes de utilização.", "whyItMatters": "Os contratos de interface da API são essenciais para garantir a clareza e o alinhamento entre os fornecedores e os consumidores de API. Esta estação fornece diretrizes para a conceção de contratos de interface da API que sejam claros, abrangentes e fáceis de compreender.", "applyInWork": "Fornecer modelos de design de contratos, formatos normalizados e processos de revisão. Assegurar que as equipas criam contratos de interface da API claros e bem definidos que descrevem as expectativas, responsabilidades e diretrizes de utilização.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Contratos de interface da API claros definidos para cada API", "Expectativas e responsabilidades definidas para os fornecedores e consumidores de API", "Orientações de utilização e boas práticas documentadas", "Redução de mal-entendidos e litígios sobre a utilização da API" ], "steps": [ { "text": "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "resourceId": "contract-first-design", "resourceTitle": "Primeira conceção do contrato", "canvasId": null }, { "text": "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar.", "resourceId": "contract-first-design", "resourceTitle": "Primeira conceção do contrato", "canvasId": null }, { "text": "Assegurar que os contratos de interface da API são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza.", "resourceId": "api-audit-checklist", "resourceTitle": "Lista de verificação de auditoria da API", "canvasId": null } ], "questions": [ "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar.", "Assegurar que os contratos de interface da API são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza.", "Fornecer modelos de design de contratos, formatos normalizados e processos de revisão. Assegurar que as equipas criam contratos de interface da API claros e bem definidos que descrevem as expectativas, responsabilidades e diretrizes de utilização.", "Os contratos de interface da API são essenciais para garantir a clareza e o alinhamento entre os fornecedores e os consumidores de API. Esta estação fornece diretrizes para a conceção de contratos de interface da API que sejam claros, abrangentes e fáceis de compreender." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "development", "slug": "method/development", "icon": "deployed-code-outline", "title": "Desenvolvimento - Criar APIs com as boas práticas", "description": "Implementar APIs utilizando as boas práticas e estruturas para garantir a qualidade, a capacidade de manutenção e a escalabilidade.", "whyItMatters": "O desenvolvimento de API é uma fase crítica que determina a qualidade e a fiabilidade da API. Esta estação fornece as boas práticas e estruturas para o desenvolvimento de APIs, garantindo que as APIs são construídas de acordo com padrões elevados e podem ser mantidas e escaladas de forma eficaz.", "applyInWork": "Fornecer estruturas de desenvolvimento, bibliotecas e normas de codificação para a implementação da API. Garantir que as equipas seguem as boas práticas e realizam revisões de código para manter um desenvolvimento de API de alta qualidade.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "APIs desenvolvidas utilizando as boas práticas e estruturas", "APIs de alta qualidade, fáceis de manter e escaláveis", "Seguimento de normas e práticas de codificação consistentes", "Redução do tempo de desenvolvimento e da dívida técnica" ], "steps": [ { "text": "Utilizar estruturas e bibliotecas estabelecidas para implementar APIs, assegurando a sua reutilização e manutenção.", "resourceId": "api-development-best-practices", "resourceTitle": "Boas práticas de desenvolvimento de API", "canvasId": null }, { "text": "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "resourceId": "contract-first-design", "resourceTitle": "Primeira conceção do contrato", "canvasId": null }, { "text": "Seguir as normas de codificação e as boas práticas para garantir um desenvolvimento de API consistente e de alta qualidade.", "resourceId": "api-development-best-practices", "resourceTitle": "Boas práticas de desenvolvimento de API", "canvasId": null } ], "questions": [ "Utilizar estruturas e bibliotecas estabelecidas para implementar APIs, assegurando a sua reutilização e manutenção.", "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "Seguir as normas de codificação e as boas práticas para garantir um desenvolvimento de API consistente e de alta qualidade.", "Fornecer estruturas de desenvolvimento, bibliotecas e normas de codificação para a implementação da API. Garantir que as equipas seguem as boas práticas e realizam revisões de código para manter um desenvolvimento de API de alta qualidade.", "O desenvolvimento de API é uma fase crítica que determina a qualidade e a fiabilidade da API. Esta estação fornece as boas práticas e estruturas para o desenvolvimento de APIs, garantindo que as APIs são construídas de acordo com padrões elevados e podem ser mantidas e escaladas de forma eficaz." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "ci-cd", "slug": "method/ci-cd", "icon": "deployed-code-update-outline", "title": "CI/CD - Automatizar a entrega da API", "description": "Implementar pipelines de integração contínua e entrega contínua (CI/CD) para automatizar a entrega de API e garantir uma qualidade consistente.", "whyItMatters": "A CI/CD é essencial para garantir que as APIs sejam entregues rapidamente, de forma confiável e com alta qualidade. Esta estação fornece diretrizes para a implementação de pipelines de CI/CD que automatizam os processos de criação, teste e disponibilização de APIs.", "applyInWork": "Fornecer estruturas, ferramentas e boas práticas de CI/CD para a entrega de API. Garantir que as equipas implementam pipelines automatizados que suportam a integração, os testes e a implementação contínuos de APIs.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Pipelines CI/CD automatizados estabelecidos para a entrega de API", "Qualidade e rastreabilidade consistentes na entrega de API", "iterações mais rápidas e redução do tempo de colocação no mercado", "Melhoria da colaboração e dos ciclos de feedback no desenvolvimento de API" ], "steps": [ { "text": "Utilize pipelines CI/CD para automatizar os processos de construção, teste e disponibilização, garantindo qualidade e rastreabilidade consistentes.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null }, { "text": "Integrar testes funcionais e não funcionais no pipeline CI/CD para garantir que as APIs cumprems normas de qualidade.", "resourceId": "api-testing-best-practices", "resourceTitle": "Boas práticas de teste de API", "canvasId": null }, { "text": "Implementar verificações de segurança automatizadas e validações de conformidade no pipeline CI/CD para garantir que as APIs são seguras e compatíveis.", "resourceId": "api-security-best-practices", "resourceTitle": "Boas práticas de segurança da API", "canvasId": null } ], "questions": [ "Utilize pipelines CI/CD para automatizar os processos de construção, teste e disponibilização, garantindo qualidade e rastreabilidade consistentes.", "Integrar testes funcionais e não funcionais no pipeline CI/CD para garantir que as APIs cumprems normas de qualidade.", "Implementar verificações de segurança automatizadas e validações de conformidade no pipeline CI/CD para garantir que as APIs são seguras e compatíveis.", "Fornecer estruturas, ferramentas e boas práticas de CI/CD para a entrega de API. Garantir que as equipas implementam pipelines automatizados que suportam a integração, os testes e a implementação contínuos de APIs.", "A CI/CD é essencial para garantir que as APIs sejam entregues rapidamente, de forma confiável e com alta qualidade. Esta estação fornece diretrizes para a implementação de pipelines de CI/CD que automatizam os processos de criação, teste e disponibilização de APIs." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "test-automation", "slug": "method/test-automation", "icon": "deployed-code-alert-outline", "title": "Automatização de testes - Garantir a qualidade da API", "description": "Implementar práticas de teste automatizadas para garantir a qualidade, fiabilidade e desempenho da API.", "whyItMatters": "Os testes automatizados são cruciais para garantir que as APIs funcionam corretamente e cumprems normas de qualidade. Esta estação fornece diretrizes para a implementação de práticas de teste automatizado que abrangem testes funcionais, de segurança e de desempenho para APIs.", "applyInWork": "Fornecer estruturas de automatização de testes, ferramentas e boas práticas para testes de API. Assegurar que as equipas implementam testes automatizados que abrangem aspectos funcionais, de segurança e de desempenho das APIs.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Práticas de teste automatizadas implementadas para APIs", "Testes funcionais, de segurança e de desempenho automatizados", "Redução do esforço de teste manual e aumento da cobertura dos testes", "Melhoria da fiabilidade e da qualidade da API" ], "steps": [ { "text": "Utilizar ferramentas de teste automatizadas para validar a funcionalidade, a segurança e o desempenho da API.", "resourceId": "api-testing-best-practices", "resourceTitle": "Boas práticas de teste de API", "canvasId": null }, { "text": "Implementar estruturas de automatização de testes que apoiem os testes de contrato, os testes de integração e os testes de ponta a ponta.", "resourceId": "api-testing-best-practices", "resourceTitle": "Boas práticas de teste de API", "canvasId": null }, { "text": "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null } ], "questions": [ "Utilizar ferramentas de teste automatizadas para validar a funcionalidade, a segurança e o desempenho da API.", "Implementar estruturas de automatização de testes que apoiem os testes de contrato, os testes de integração e os testes de ponta a ponta.", "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "Fornecer estruturas de automatização de testes, ferramentas e boas práticas para testes de API. Assegurar que as equipas implementam testes automatizados que abrangem aspectos funcionais, de segurança e de desempenho das APIs.", "Os testes automatizados são cruciais para garantir que as APIs funcionam corretamente e cumprems normas de qualidade. Esta estação fornece diretrizes para a implementação de práticas de teste automatizado que abrangem testes funcionais, de segurança e de desempenho para APIs." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "release-management", "slug": "method/release-management", "icon": "rocket-launch-outline", "title": "Gestão de versões - Gerir eficazmente as versões da API", "description": "Implementar práticas de gestão de lançamentos para garantir lançamentos de API sem problemas e controlados.", "whyItMatters": "A gestão eficaz de lançamentos é essencial para garantir que os lançamentos de APIs sejam fáceis, controlados e alinhados com as necessidades do negócio. Esta estação fornece diretrizes para a gestão de lançamentos de API, incluindo versões, estratégias de implementação e procedimentos de reversão.", "applyInWork": "Fornecer estruturas de gestão de versões, diretrizes de controlo de versões e estratégias de implementação. Assegurar que as equipas seguem as boas práticas para a gestão de lançamentos de API, incluindo procedimentos de versão, implementação e reversão.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Lançamentos de API controlados e sem problemas", "Definição de estratégias de versão e disponibilização", "Procedimentos de reversão estabelecidos para libertações de API", "Redução dos riscos associados às alterações da API" ], "steps": [ { "text": "Definir estratégias de controlo de versões para as APIs para gerir as alterações e garantir a compatibilidade com as versões anteriores.", "resourceId": "api-versioning-best-practices", "resourceTitle": "Boas práticas de controlo de versões da API", "canvasId": null }, { "text": "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "resourceId": "apiops-CI-CD-for-apis", "resourceTitle": "APIOps CI/CD para APIs", "canvasId": null }, { "text": "Estabelecer procedimentos de reversão para reverter rapidamente as alterações em caso de problemas durante os lançamentos da API.", "resourceId": "", "resourceTitle": "", "canvasId": null } ], "questions": [ "Definir estratégias de controlo de versões para as APIs para gerir as alterações e garantir a compatibilidade com as versões anteriores.", "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "Estabelecer procedimentos de reversão para reverter rapidamente as alterações em caso de problemas durante os lançamentos da API.", "Fornecer estruturas de gestão de versões, diretrizes de controlo de versões e estratégias de implementação. Assegurar que as equipas seguem as boas práticas para a gestão de lançamentos de API, incluindo procedimentos de versão, implementação e reversão.", "A gestão eficaz de lançamentos é essencial para garantir que os lançamentos de APIs sejam fáceis, controlados e alinhados com as necessidades do negócio. Esta estação fornece diretrizes para a gestão de lançamentos de API, incluindo versões, estratégias de implementação e procedimentos de reversão." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "service-agreements", "slug": "method/service-agreements", "icon": "contract-outline", "title": "Acordos de serviço - Definir níveis de serviço de API", "description": "Estabelecer acordos de serviço que definam as expectativas, os níveis de serviço e as responsabilidades dos fornecedores e consumidores de API.", "whyItMatters": "Os acordos de serviço são essenciais para garantir a clareza e o alinhamento entre os fornecedores de API e os consumidores. Esta estação fornece diretrizes para a criação de acordos de serviço que definem expectativas, níveis de serviço e responsabilidades, reduzindo mal-entendidos e disputas.", "applyInWork": "Fornecer modelos de contratos de serviço, formatos normalizados e processos de revisão. Garantir que as equipas criam contratos de serviço claros e bem definidos que descrevem as expectativas, os níveis de serviço e as responsabilidades dos fornecedores e consumidores de API.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Acordos de serviço claros definidos para cada API", "Expectativas e níveis de serviço definidos para fornecedores e consumidores de API", "Responsabilidades e processos de apoio documentados", "Melhoria da comunicação e da colaboração entre as equipas de API" ], "steps": [ { "text": "Defina acordos de serviço que descrevam as expectativas, os níveis de serviço e as responsabilidades de cada API.", "resourceId": "service-agreement-template", "resourceTitle": "Modelo de contrato de serviço", "canvasId": null }, { "text": "Utilize formatos normalizados para criar contratos de serviço legíveis por máquina que sejam fáceis de partilhar e validar.", "resourceId": "service-agreement-template", "resourceTitle": "Modelo de contrato de serviço", "canvasId": null }, { "text": "Assegurar que os acordos de serviço são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza.", "resourceId": "service-agreement-template", "resourceTitle": "Modelo de contrato de serviço", "canvasId": null } ], "questions": [ "Defina acordos de serviço que descrevam as expectativas, os níveis de serviço e as responsabilidades de cada API.", "Utilize formatos normalizados para criar contratos de serviço legíveis por máquina que sejam fáceis de partilhar e validar.", "Assegurar que os acordos de serviço são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza.", "Fornecer modelos de contratos de serviço, formatos normalizados e processos de revisão. Garantir que as equipas criam contratos de serviço claros e bem definidos que descrevem as expectativas, os níveis de serviço e as responsabilidades dos fornecedores e consumidores de API.", "Os acordos de serviço são essenciais para garantir a clareza e o alinhamento entre os fornecedores de API e os consumidores. Esta estação fornece diretrizes para a criação de acordos de serviço que definem expectativas, níveis de serviço e responsabilidades, reduzindo mal-entendidos e disputas." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "api-consumer-adoption", "slug": "method/api-consumer-adoption", "icon": "chart-data-outline", "title": "Adoção pelo consumidor da API - Impulsionar a utilização da API", "description": "Implementar estratégias para promover a adoção e o envolvimento dos consumidores de API, assegurando que as APIs são utilizadas eficazmente.", "whyItMatters": "A adoção pelos consumidores de APIs é crucial para a concretização do valor das APIs. Esta estação fornece estratégias e boas práticas para envolver os consumidores de API, garantindo que eles entendam como utilizar as APIs de forma eficaz e obter valor delas.", "applyInWork": "Fornecer recursos de integração, materiais educativos e estratégias de envolvimento para os consumidores da API. Assegurar que as equipas implementam estratégias que promovem a adoção, o envolvimento e a satisfação dos consumidores da API.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Estratégias de adoção pelos consumidores da API implementadas", "Aumento da utilização e do envolvimento da API", "Consumidores da API informados sobre as características e vantagens da API", "Melhoria da satisfação e da lealdade do consumidor API" ], "steps": [ { "text": "Desenvolver processos de integração e recursos para ajudar os consumidores de API a compreender como utilizar as APIs de forma eficaz.", "resourceId": "api-onboarding-best-practices", "resourceTitle": "Boas práticas de integração de API", "canvasId": null }, { "text": "Criar materiais educativos (por exemplo, tutoriais, documentação) que expliquem as características, as vantagens e os padrões de utilização da API.", "resourceId": "api-community-engagement-strategies", "resourceTitle": "Estratégias de envolvimento da comunidade API", "canvasId": null }, { "text": "Interagir com os consumidores da API através de ciclos de feedback, canais de apoio e fóruns da comunidade para compreender as suas necessidades e melhorar a adoção da API.", "resourceId": "api-community-engagement-strategies", "resourceTitle": "Estratégias de envolvimento da comunidade API", "canvasId": null } ], "questions": [ "Desenvolver processos de integração e recursos para ajudar os consumidores de API a compreender como utilizar as APIs de forma eficaz.", "Criar materiais educativos (por exemplo, tutoriais, documentação) que expliquem as características, as vantagens e os padrões de utilização da API.", "Interagir com os consumidores da API através de ciclos de feedback, canais de apoio e fóruns da comunidade para compreender as suas necessidades e melhorar a adoção da API.", "Fornecer recursos de integração, materiais educativos e estratégias de envolvimento para os consumidores da API. Assegurar que as equipas implementam estratégias que promovem a adoção, o envolvimento e a satisfação dos consumidores da API.", "A adoção pelos consumidores de APIs é crucial para a concretização do valor das APIs. Esta estação fornece estratégias e boas práticas para envolver os consumidores de API, garantindo que eles entendam como utilizar as APIs de forma eficaz e obter valor delas." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "api-promotion", "slug": "method/api-promotion", "icon": "brand-awareness-outline", "title": "Promoção da API - Aumente a visibilidade e a utilização da API", "description": "Promover as APIs para aumentar a visibilidade, a utilização e a adoção entre os públicos-alvo.", "whyItMatters": "A promoção das APIs é essencial para aumentar a sua visibilidade e impulsionar a sua utilização. Esta estação fornece estratégias e boas práticas para promover eficazmente as APIs junto de públicos-alvo, assegurando que estes têm conhecimento das APIs e compreendem o seu valor.", "applyInWork": "Fornecer estratégias de marketing, materiais promocionais e recursos de envolvimento da comunidade. Assegurar que as equipas implementam estratégias eficazes de promoção da API que aumentam a visibilidade, a utilização e a adoção entre os públicos-alvo.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Estratégias de promoção da API implementadas", "Maior visibilidade e conhecimento da API", "Taxas de utilização e adoção de API mais elevadas", "Melhoria do envolvimento e da satisfação dos consumidores da API" ], "steps": [ { "text": "Desenvolver estratégias de marketing para promover as APIs junto de públicos-alvo, incluindo redes sociais, blogues e webinars.", "resourceId": "api-community-engagement-strategies", "resourceTitle": "Estratégias de envolvimento da comunidade API", "canvasId": null }, { "text": "Criar materiais promocionais (por exemplo, estudos de casos, histórias de sucesso) que realcem o valor e as vantagens das APIs.", "resourceId": "api-community-engagement-strategies", "resourceTitle": "Estratégias de envolvimento da comunidade API", "canvasId": null }, { "text": "Participar em comunidades e fóruns de API para partilhar actualizações da API, recolher feedback e promover a utilização da API.", "resourceId": "api-community-engagement-strategies", "resourceTitle": "Estratégias de envolvimento da comunidade API", "canvasId": null } ], "questions": [ "Desenvolver estratégias de marketing para promover as APIs junto de públicos-alvo, incluindo redes sociais, blogues e webinars.", "Criar materiais promocionais (por exemplo, estudos de casos, histórias de sucesso) que realcem o valor e as vantagens das APIs.", "Participar em comunidades e fóruns de API para partilhar actualizações da API, recolher feedback e promover a utilização da API.", "Fornecer estratégias de marketing, materiais promocionais e recursos de envolvimento da comunidade. Assegurar que as equipas implementam estratégias eficazes de promoção da API que aumentam a visibilidade, a utilização e a adoção entre os públicos-alvo.", "A promoção das APIs é essencial para aumentar a sua visibilidade e impulsionar a sua utilização. Esta estação fornece estratégias e boas práticas para promover eficazmente as APIs junto de públicos-alvo, assegurando que estes têm conhecimento das APIs e compreendem o seu valor." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "partner-integration", "slug": "method/partner-integration", "icon": "integration-instructions-outline", "title": "Integração de parceiros - Colaborar com parceiros", "description": "Facilitar as integrações de parceiros para melhorar as capacidades da API e expandir o alcance.", "whyItMatters": "As integrações de parceiros podem melhorar as capacidades da API e expandir o seu alcance. Esta estação fornece diretrizes para colaborar com os parceiros na integração das suas APIs, garantindo uma interoperabilidade perfeita e a criação de valor.", "applyInWork": "Fornecer estruturas de integração de parceiros, diretrizes e ferramentas de monitorização. Garantir que as equipas colaboram eficazmente com os parceiros para melhorar as capacidades da API, expandir o alcance e impulsionar a inovação.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Processos de integração de parceiros estabelecidos", "Capacidades API melhoradas através de API de parceiros", "Maior alcance e oportunidades de mercado através de parcerias", "Melhoria da colaboração e da inovação com os parceiros" ], "steps": [ { "text": "Identifique potenciais parceiros cujas APIs possam melhorar as suas capacidades de API e a sua proposta de valor.", "resourceId": "ecosystem-vision-template", "resourceTitle": "Modelo de visão do ecossistema", "canvasId": null }, { "text": "Estabelecer processos de integração e orientações para colaborar com os parceiros, incluindo a integração técnica, a partilha de dados e o apoio.", "resourceId": "partner-integration-guidelines", "resourceTitle": "Diretrizes de integração de parceiros", "canvasId": null }, { "text": "Monitorize o desempenho e a conformidade da API do parceiro para garantir a fiabilidade e o alinhamento com a sua estratégia de API.", "resourceId": "partner-integration-guidelines", "resourceTitle": "Diretrizes de integração de parceiros", "canvasId": null } ], "questions": [ "Identifique potenciais parceiros cujas APIs possam melhorar as suas capacidades de API e a sua proposta de valor.", "Estabelecer processos de integração e orientações para colaborar com os parceiros, incluindo a integração técnica, a partilha de dados e o apoio.", "Monitorize o desempenho e a conformidade da API do parceiro para garantir a fiabilidade e o alinhamento com a sua estratégia de API.", "Fornecer estruturas de integração de parceiros, diretrizes e ferramentas de monitorização. Garantir que as equipas colaboram eficazmente com os parceiros para melhorar as capacidades da API, expandir o alcance e impulsionar a inovação.", "As integrações de parceiros podem melhorar as capacidades da API e expandir o seu alcance. Esta estação fornece diretrizes para colaborar com os parceiros na integração das suas APIs, garantindo uma interoperabilidade perfeita e a criação de valor." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "api-mindset", "slug": "method/api-mindset", "icon": "psychology-outline", "title": "Mentalidade API - Promover uma cultura API-First", "description": "Cultivar uma mentalidade API-first em toda a organização para impulsionar a inovação e a colaboração.", "whyItMatters": "Uma mentalidade API-first é essencial para promover a inovação e a colaboração em toda a organização. Esta estação fornece estratégias para cultivar uma cultura API-first, garantindo que as APIs sejam vistas como activos estratégicos que geram valor de negócio.", "applyInWork": "Fornecer programas de formação, recursos e estratégias de comunicação para promover uma cultura de prioridade à API. Assegurar que as equipas compreendem o valor das APIs e estão habilitadas a conduzir a estratégia e as iniciativas das APIs.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Cultura API-first estabelecida em toda a organização", "Maior inovação e colaboração através de API", "Equipas de API habilitadas a conduzir a estratégia e as iniciativas de API", "Melhoria do alinhamento entre os objetivos de negócio e o desenvolvimento de API" ], "steps": [ { "text": "Promover o valor das APIs como activos estratégicos que geram valor de negócio e inovação.", "resourceId": "ecosystem-vision-template", "resourceTitle": "Modelo de visão do ecossistema", "canvasId": null }, { "text": "Incentivar a colaboração multifuncional entre equipas de API, unidades empresariais e partes interessadas para alinhar as iniciativas de API com os objetivos empresariais.", "resourceId": "cross-functional-collaboration-best-practices", "resourceTitle": "Boas práticas de colaboração interfuncional", "canvasId": null }, { "text": "Fornecer formação e recursos para ajudar as equipas a adotar uma mentalidade de prioridade à API e a compreender as vantagens das APIs.", "resourceId": "api-training-programs", "resourceTitle": "Programas de formação API", "canvasId": null } ], "questions": [ "Promover o valor das APIs como activos estratégicos que geram valor de negócio e inovação.", "Incentivar a colaboração multifuncional entre equipas de API, unidades empresariais e partes interessadas para alinhar as iniciativas de API com os objetivos empresariais.", "Fornecer formação e recursos para ajudar as equipas a adotar uma mentalidade de prioridade à API e a compreender as vantagens das APIs.", "Fornecer programas de formação, recursos e estratégias de comunicação para promover uma cultura de prioridade à API. Assegurar que as equipas compreendem o valor das APIs e estão habilitadas a conduzir a estratégia e as iniciativas das APIs.", "Uma mentalidade API-first é essencial para promover a inovação e a colaboração em toda a organização. Esta estação fornece estratégias para cultivar uma cultura API-first, garantindo que as APIs sejam vistas como activos estratégicos que geram valor de negócio." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "roles-and-responsibilities", "slug": "method/roles-and-responsibilities", "icon": "manage-accounts-outline", "title": "Funções e responsabilidades - Definir as estruturas da equipa API", "description": "Definir funções e responsabilidades claras para as equipas de API para garantir uma colaboração e responsabilização eficazes.", "whyItMatters": "Funções e responsabilidades claras são essenciais para uma colaboração e responsabilidade eficazes nas equipas de API. Esta estação fornece diretrizes para a definição das estruturas, funções e responsabilidades da equipa, assegurando que todos compreendem as suas contribuições para as iniciativas da API.", "applyInWork": "Fornecer orientações sobre a estrutura da equipa, definições de funções e estratégias de comunicação. Assegurar que as equipas têm funções e responsabilidades claras que promovem a colaboração eficaz e a responsabilização nas iniciativas da API.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Funções e responsabilidades claras definidas para as equipas de API", "Colaboração e responsabilização eficazes nas equipas API", "Melhoria da comunicação e do alinhamento entre os membros da equipa", "Redução da confusão e da sobreposição de responsabilidades" ], "steps": [ { "text": "Definir estruturas de equipa e funções para equipas de API, incluindo proprietários de produtos de API, programadores, arquitectos e operações.", "resourceId": "api-team-structure-guidelines", "resourceTitle": "Diretrizes da estrutura da equipa API", "canvasId": null }, { "text": "Estabelecer responsabilidades claras para cada função, incluindo a conceção, o desenvolvimento, os testes e as operações da API.", "resourceId": "role-communication-best-practices", "resourceTitle": "Boas práticas de comunicação de funções", "canvasId": null }, { "text": "Assegurar que as funções e responsabilidades são comunicadas a todos os membros da equipa e partes interessadas para garantir o alinhamento.", "resourceId": "role-communication-best-practices", "resourceTitle": "Boas práticas de comunicação de funções", "canvasId": null } ], "questions": [ "Definir estruturas de equipa e funções para equipas de API, incluindo proprietários de produtos de API, programadores, arquitectos e operações.", "Estabelecer responsabilidades claras para cada função, incluindo a conceção, o desenvolvimento, os testes e as operações da API.", "Assegurar que as funções e responsabilidades são comunicadas a todos os membros da equipa e partes interessadas para garantir o alinhamento.", "Fornecer orientações sobre a estrutura da equipa, definições de funções e estratégias de comunicação. Assegurar que as equipas têm funções e responsabilidades claras que promovem a colaboração eficaz e a responsabilização nas iniciativas da API.", "Funções e responsabilidades claras são essenciais para uma colaboração e responsabilidade eficazes nas equipas de API. Esta estação fornece diretrizes para a definição das estruturas, funções e responsabilidades da equipa, assegurando que todos compreendem as suas contribuições para as iniciativas da API." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "upskilling", "slug": "method/upskilling", "icon": "school-outline", "title": "Upskilling - Melhorar as competências e conhecimentos em matéria de API", "description": "Fornecer formação e recursos para melhorar as competências e os conhecimentos sobre API em toda a organização.", "whyItMatters": "A aprendizagem contínua e a atualização de competências são essenciais para manter as equipas de API actualizadas com as mais recentes tecnologias, práticas e tendências. Esta estação fornece programas de formação e recursos para melhorar as competências e os conhecimentos sobre API, garantindo que as equipas estão equipadas para fornecer APIs de alta qualidade.", "applyInWork": "Fornecer programas de formação, recursos e ferramentas de avaliação para melhorar as competências e os conhecimentos em matéria de API. Assegurar que as equipas têm acesso a oportunidades de aprendizagem contínua que lhes permitam impulsionar a inovação e a qualidade da API.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Melhoria das competências e conhecimentos em matéria de API em toda a organização", "Maior proficiência na conceção, desenvolvimento e gestão de API", "Melhoria da capacidade de adoção de novas tecnologias e práticas", "Equipas capacitadas para impulsionar a inovação e a qualidade da API" ], "steps": [ { "text": "Identificar as principais competências e áreas de conhecimento da API que precisam de ser melhoradas, como a conceção, a segurança e o desempenho da API.", "resourceId": "api-training-programs", "resourceTitle": "Programas de formação API", "canvasId": null } ], "questions": [ "Identificar as principais competências e áreas de conhecimento da API que precisam de ser melhoradas, como a conceção, a segurança e o desempenho da API.", "Fornecer programas de formação, recursos e ferramentas de avaliação para melhorar as competências e os conhecimentos em matéria de API. Assegurar que as equipas têm acesso a oportunidades de aprendizagem contínua que lhes permitam impulsionar a inovação e a qualidade da API.", "A aprendizagem contínua e a atualização de competências são essenciais para manter as equipas de API actualizadas com as mais recentes tecnologias, práticas e tendências. Esta estação fornece programas de formação e recursos para melhorar as competências e os conhecimentos sobre API, garantindo que as equipas estão equipadas para fornecer APIs de alta qualidade." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "operating-guidelines", "slug": "method/operating-guidelines", "icon": "list-alt-outline", "title": "Diretrizes operacionais - Estabelecer a governação da API", "description": "Estabelecer diretrizes operacionais e práticas de governação para garantir uma gestão e qualidade consistentes da API.", "whyItMatters": "A governação eficaz da API é essencial para garantir uma gestão, qualidade e conformidade consistentes da API. Esta estação fornece diretrizes operacionais e práticas de governação que ajudam as equipas a gerir as APIs de forma eficaz, assegurando o seu alinhamento com as normas organizacionais e as boas práticas.", "applyInWork": "Fornecer diretrizes operacionais, quadros de governação e ferramentas de monitorização para a gestão de API. Assegurar que as equipas seguem as práticas estabelecidas que promovem a gestão consistente da API, a qualidade e a conformidade com as normas organizacionais.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Práticas de governação da API estabelecidas", "Gestão e qualidade consistentes da API em toda a organização", "Conformidade com as normas organizacionais e as boas práticas", "Melhoria da visibilidade e do controlo das iniciativas API" ], "steps": [ { "text": "Definir diretrizes operacionais baseadas nos Ciclos APIOps que descrevem os processos, as normas e as boas práticas para a gestão de API.", "resourceId": "", "resourceTitle": "", "canvasId": null }, { "text": "Estabelecer práticas de governação que garantam que as APIs são geridas de forma consistente, incluindo análises, auditorias e verificações de conformidade.", "resourceId": "", "resourceTitle": "", "canvasId": null }, { "text": "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação", "resourceId": "api-metrics-and-analytics", "resourceTitle": "Métricas e análise de API", "canvasId": null } ], "questions": [ "Definir diretrizes operacionais baseadas nos Ciclos APIOps que descrevem os processos, as normas e as boas práticas para a gestão de API.", "Estabelecer práticas de governação que garantam que as APIs são geridas de forma consistente, incluindo análises, auditorias e verificações de conformidade.", "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação", "Fornecer diretrizes operacionais, quadros de governação e ferramentas de monitorização para a gestão de API. Assegurar que as equipas seguem as práticas estabelecidas que promovem a gestão consistente da API, a qualidade e a conformidade com as normas organizacionais.", "A governação eficaz da API é essencial para garantir uma gestão, qualidade e conformidade consistentes da API. Esta estação fornece diretrizes operacionais e práticas de governação que ajudam as equipas a gerir as APIs de forma eficaz, assegurando o seu alinhamento com as normas organizacionais e as boas práticas." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "portfolio-management", "slug": "method/portfolio-management", "icon": "cases-outline", "title": "Gestão de portfólio - Gerir eficazmente o portfólio de API", "description": "Gerir eficazmente a carteira de API para garantir o alinhamento com os objetivos de negócio e as iniciativas estratégicas.", "whyItMatters": "O gestão eficaz do portfólio de APIs é essencial para garantir que as APIs se alinhem às metas comerciais e às iniciativas estratégicas. Esta estação fornece diretrizes para o gestão do portfólio de APIs, garantindo que as APIs sejam priorizadas, monitoradas e otimizadas para fornecer o máximo de valor.", "applyInWork": "Fornecer estruturas de gestão de carteiras, critérios de priorização e ferramentas de monitorização para a gestão de API. Assegurar que as equipas gerem eficazmente o portfólio de API, garantindo o alinhamento com os objetivos de negócio, as iniciativas estratégicas e a obtenção do máximo valor.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Estabelecimento de práticas de gestão de carteiras API", "APIs alinhadas com objetivos de negócio e iniciativas estratégicas", "Priorização e otimização de APIs com base no valor e no impacto", "Melhoria da visibilidade e do controlo da carteira de API" ], "steps": [ { "text": "Definir práticas de gestão da carteira que descrevam os processos de gestão da carteira de API, incluindo a definição de prioridades, a monitorização e a otimização.", "resourceId": "api-portfolio-management-guidelines", "resourceTitle": "Diretrizes de gestão da carteira API", "canvasId": null } ], "questions": [ "Definir práticas de gestão da carteira que descrevam os processos de gestão da carteira de API, incluindo a definição de prioridades, a monitorização e a otimização.", "Fornecer estruturas de gestão de carteiras, critérios de priorização e ferramentas de monitorização para a gestão de API. Assegurar que as equipas gerem eficazmente o portfólio de API, garantindo o alinhamento com os objetivos de negócio, as iniciativas estratégicas e a obtenção do máximo valor.", "O gestão eficaz do portfólio de APIs é essencial para garantir que as APIs se alinhem às metas comerciais e às iniciativas estratégicas. Esta estação fornece diretrizes para o gestão do portfólio de APIs, garantindo que as APIs sejam priorizadas, monitoradas e otimizadas para fornecer o máximo de valor." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] }, { "id": "budget-and-resource-management", "slug": "method/budget-and-resource-management", "icon": "money-bag-outline", "title": "Orçamento e gestão de recursos - Otimizar os investimentos em API", "description": "Otimizar o orçamento e a gestão de recursos para as iniciativas API, a fim de garantir investimentos e atribuição de recursos eficazes.", "whyItMatters": "A gestão eficaz do orçamento e dos recursos é essencial para garantir que as iniciativas de API sejam bem financiadas e dotadas de recursos. Esta estação fornece diretrizes para otimizar a gestão do orçamento e dos recursos, assegurando que as iniciativas de API estão alinhadas com os objetivos de negócio e proporcionam o máximo valor.", "applyInWork": "Fornecer estruturas de gestão orçamental, critérios de prioritização e ferramentas de monitorização para iniciativas de API. Assegurar que as equipas gerem eficazmente os orçamentos e os recursos, optimizando os investimentos no desenvolvimento e na gestão de API para obter o máximo valor.", "group": "Sub-estações do ciclo de vida API", "lifecycleStage": "supporting", "outcomes": [ "Práticas de gestão orçamental e de recursos estabelecidas para as iniciativas API", "Afetação efectiva de recursos às iniciativas API", "Investimentos optimizados no desenvolvimento e gestão de API", "Melhoria da visibilidade financeira e do controlo das iniciativas API" ], "steps": [ { "text": "Definir práticas de gestão orçamental e de recursos que descrevam os processos de gestão de orçamentos e recursos para iniciativas de API.", "resourceId": "api-portfolio-management-guidelines", "resourceTitle": "Diretrizes de gestão da carteira API", "canvasId": null } ], "questions": [ "Definir práticas de gestão orçamental e de recursos que descrevam os processos de gestão de orçamentos e recursos para iniciativas de API.", "Fornecer estruturas de gestão orçamental, critérios de prioritização e ferramentas de monitorização para iniciativas de API. Assegurar que as equipas gerem eficazmente os orçamentos e os recursos, optimizando os investimentos no desenvolvimento e na gestão de API para obter o máximo valor.", "A gestão eficaz do orçamento e dos recursos é essencial para garantir que as iniciativas de API sejam bem financiadas e dotadas de recursos. Esta estação fornece diretrizes para otimizar a gestão do orçamento e dos recursos, assegurando que as iniciativas de API estão alinhadas com os objetivos de negócio e proporcionam o máximo valor." ], "criteria": [], "criteriaDetails": [], "stakeholders": [], "evidence": [] } ], "stakeholders": [ { "id": "api-architect", "sourceKey": "api-architect", "sourceStakeholderId": "api-architect", "title": "Arquiteto API", "description": "Responsável pela arquitetura API, pelos princípios de desenho e pela qualidade dos contratos de interface.", "involvement": "" }, { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "" }, { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "" }, { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "" }, { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "" }, { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "" }, { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "" }, { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "" }, { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "" }, { "id": "partner-specialist", "sourceKey": "partner-specialist", "sourceStakeholderId": "partner-specialist", "title": "Gestor de parceiros ou fornecedores", "description": "Coordena relações com parceiros, fornecedores ou prestadores externos que influenciam a estratégia e entrega da capacidade ou API.", "involvement": "" }, { "id": "customer-specialist", "sourceKey": "customer-specialist", "sourceStakeholderId": "customer-specialist", "title": "Representante de cliente ou parceiro", "description": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "involvement": "" }, { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "" }, { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "" }, { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "" }, { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "" }, { "id": "governance-specialist", "sourceKey": "governance-specialist", "sourceStakeholderId": "governance-specialist", "title": "Responsável pela governação API", "description": "Representa práticas de revisão, auditoria e governação em toda a organização para qualidade e conformidade das APIs.", "involvement": "" }, { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "" }, { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "" }, { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "" }, { "id": "api-program-owner", "sourceKey": "api-program-owner", "sourceStakeholderId": "api-program-owner", "title": "Responsável pelo programa API", "description": "Coordena as práticas do portefólio de APIs, o alinhamento organizacional e o desenvolvimento de capacidades API a longo prazo.", "involvement": "" }, { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "" }, { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "" } ], "routeProfiles": [ { "id": "api-architect", "stakeholderId": "api-architect", "title": "Arquiteto API", "summary": "Responsável pela arquitetura API, pelos princípios de desenho e pela qualidade dos contratos de interface.", "stakeholder": { "id": "api-architect", "sourceKey": "api-architect", "sourceStakeholderId": "api-architect", "title": "Arquiteto API", "description": "Responsável pela arquitetura API, pelos princípios de desenho e pela qualidade dos contratos de interface.", "involvement": "" }, "cycles": [ { "id": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." } ], "stations": [ { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." } ], "canvases": [ { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" } ], "decisions": [ "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência." ], "outputs": [ "Corte APIs redundantes e reduza os custos da plataforma de nuvem", "Implementar uma governação consistente snum forte controlo do topo para a base", "Conceção para reutilização interna e escalabilidade externa", "architecture-decision", "documentation", "platform-config", "metrics" ], "recommendedResources": [ { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-metrics-and-analytics", "slug": "resources/api-metrics-and-analytics", "title": "Métricas e análise de API", "description": "Um recurso para definir, recolher e analisar o desempenho da API e os dados de utilização para alinhar os KPIs técnicos com os resultados de negócio.", "category": "guideline", "icon": "edit-document-outline", "order": 119, "outcomes": [ "Melhor compreensão dos princípios de métrica e análise de API", "Abordagem normalizada utilizando métricas e análise de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação" ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "partner-integration-guidelines", "slug": "resources/partner-integration-guidelines", "title": "Diretrizes de integração de parceiros", "description": "Listas de verificação de integração e padrões de comunicação para gerir os aspectos técnicos e legais das relações com APIs de terceiros.", "category": "guideline", "icon": "edit-document-outline", "order": 164, "outcomes": [ "Melhor compreensão dos princípios das diretrizes de integração de parceiros", "Abordagem normalizada utilizando as Diretrizes de Integração de Parceiros", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Estabelecer processos de integração e orientações para colaborar com os parceiros, incluindo a integração técnica, a partilha de dados e o apoio.", "Monitorize o desempenho e a conformidade da API do parceiro para garantir a fiabilidade e o alinhamento com a sua estratégia de API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "promptIds": [ "api-architect:facilitate-station", "api-architect:use-resources", "api-architect:next-actions" ] }, { "id": "integration-architect", "stakeholderId": "integration-architect", "title": "Arquiteto de integração", "summary": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "stakeholder": { "id": "integration-architect", "sourceKey": "integration-architect", "sourceStakeholderId": "integration-architect", "title": "Arquiteto de integração", "description": "Desenha abordagens de integração e estilos de implementação que ligam a capacidade ou API a outros sistemas.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." }, { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." }, { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." }, { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." }, { "id": "api-consumer-experience", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento." }, { "id": "api-delivery", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia." }, { "id": "api-audit", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição." }, { "id": "api-publishing", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." } ], "canvases": [ { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "interactionCanvas", "title": "Canvas de Interação" }, { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "capabilityBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da Capacidade" }, { "id": "consumerExperienceRequirementsCanvas", "title": "Canvas de Requisitos da Experiência do Utilizador" }, { "id": "restCanvas", "title": "Canvas REST" }, { "id": "eventCanvas", "title": "Canvas de Eventos" }, { "id": "graphqlCanvas", "title": "Canvas GraphQL" } ], "decisions": [ "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência." ], "outputs": [ "Corte APIs redundantes e reduza os custos da plataforma de nuvem", "Implementar uma governação consistente snum forte controlo do topo para a base", "Conceção para reutilização interna e escalabilidade externa", "architecture-decision", "documentation", "platform-config", "metrics", "Conceção de API bem documentada e coerente" ], "recommendedResources": [ { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "contract-first-design", "slug": "resources/contract-first-design", "title": "Primeira conceção do contrato", "description": "Uma diretriz que defende abordagens API-first utilizando contratos formais (por exemplo, OpenAPI) para alinhar as partes interessadas antes do desenvolvimento.", "category": "guideline", "icon": "edit-document-outline", "order": 146, "outcomes": [ "Melhor compreensão dos princípios de conceção da primeira fase do contrato", "Abordagem normalizada utilizando a conceção orientada por contrato", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar." ], "canvasId": null, "sourcePath": "src/snippets/api-contract-example.yaml", "sourceUrl": null, "contentMarkdown": "openapi: 3.0.3\r\ninfo:\r\n title: Sample Catalog API\r\n version: 1.0.0\r\n description: |\r\n Starter example for a read-only APIOps Cycles API.\r\n This example keeps the contract audit-friendly and easy to extend.\r\nservers:\r\n - url: /v1\r\n description: Versioned API base path\r\ntags:\r\n - name: catalog\r\n description: Browse and search catalog items\r\npaths:\r\n /items:\r\n get:\r\n tags: [catalog]\r\n summary: List catalog items\r\n description: Returns a paginated list of public catalog items.\r\n operationId: listItems\r\n parameters:\r\n - $ref: \"#/components/parameters/searchTerm\"\r\n - $ref: \"#/components/parameters/categoryId\"\r\n - $ref: \"#/components/parameters/page\"\r\n - $ref: \"#/components/parameters/pageSize\"\r\n responses:\r\n \"200\":\r\n description: Item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n examples:\r\n default:\r\n value:\r\n data:\r\n - itemId: item-123\r\n slug: blue-widget\r\n name: Blue Widget\r\n status: published\r\n page:\r\n number: 1\r\n size: 20\r\n totalItems: 1\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"429\":\r\n $ref: \"#/components/responses/TooManyRequests\"\r\n /items/{itemId}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by id\r\n description: Returns a single public catalog item by opaque identifier.\r\n operationId: getItemById\r\n parameters:\r\n - $ref: \"#/components/parameters/itemId\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /items/by-slug/{slug}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by slug\r\n description: Returns a single item by public slug.\r\n operationId: getItemBySlug\r\n parameters:\r\n - $ref: \"#/components/parameters/slug\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /categories/{categoryId}/items:\r\n get:\r\n tags: [catalog]\r\n summary: List items in category\r\n description: Returns public items in a category.\r\n operationId: listItemsByCategory\r\n parameters:\r\n - $ref: \"#/components/parameters/categoryId\"\r\n responses:\r\n \"200\":\r\n description: Category item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\ncomponents:\r\n parameters:\r\n itemId:\r\n name: itemId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: item-123\r\n slug:\r\n name: slug\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9]+(?:-[a-z0-9]+)*$\"\r\n example: blue-widget\r\n categoryId:\r\n name: categoryId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: home-goods\r\n searchTerm:\r\n name: searchTerm\r\n in: query\r\n required: false\r\n schema:\r\n type: string\r\n minLength: 1\r\n example: widget\r\n page:\r\n name: page\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n default: 1\r\n pageSize:\r\n name: pageSize\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n maximum: 100\r\n default: 20\r\n responses:\r\n BadRequest:\r\n description: Validation failed\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n examples:\r\n default:\r\n value:\r\n code: BAD_REQUEST\r\n message: Invalid request\r\n NotFound:\r\n description: Resource not found\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n TooManyRequests:\r\n description: Rate limit exceeded\r\n headers:\r\n Retry-After:\r\n schema:\r\n type: integer\r\n description: Seconds until the next allowed request.\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n schemas:\r\n ItemListResponse:\r\n type: object\r\n required: [data, page]\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/ItemSummary\"\r\n page:\r\n $ref: \"#/components/schemas/Page\"\r\n ItemSummary:\r\n type: object\r\n required: [itemId, slug, name, status]\r\n properties:\r\n itemId:\r\n type: string\r\n slug:\r\n type: string\r\n name:\r\n type: string\r\n status:\r\n type: string\r\n enum: [published, hidden]\r\n ItemDetail:\r\n allOf:\r\n - $ref: \"#/components/schemas/ItemSummary\"\r\n - type: object\r\n properties:\r\n description:\r\n type: string\r\n categories:\r\n type: array\r\n items:\r\n type: string\r\n variants:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/Variant\"\r\n Variant:\r\n type: object\r\n required: [variantId, sku, price, inventory]\r\n properties:\r\n variantId:\r\n type: string\r\n sku:\r\n type: string\r\n price:\r\n $ref: \"#/components/schemas/Price\"\r\n inventory:\r\n $ref: \"#/components/schemas/Inventory\"\r\n Price:\r\n type: object\r\n required: [amount, currency]\r\n properties:\r\n amount:\r\n type: number\r\n format: decimal\r\n currency:\r\n type: string\r\n example: EUR\r\n Inventory:\r\n type: object\r\n required: [available]\r\n properties:\r\n available:\r\n type: integer\r\n minimum: 0\r\n reserved:\r\n type: integer\r\n minimum: 0\r\n source:\r\n type: string\r\n Page:\r\n type: object\r\n required: [number, size, totalItems]\r\n properties:\r\n number:\r\n type: integer\r\n size:\r\n type: integer\r\n totalItems:\r\n type: integer\r\n ErrorResponse:\r\n type: object\r\n required: [code, message]\r\n properties:\r\n code:\r\n type: string\r\n message:\r\n type: string\r\n", "draft": true }, { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityBusinessModelCanvas", "slug": "resources/capability-business-model-canvas", "title": "Canvas do Modelo de Negócio da Capacidade", "description": "Um canvas de modelo de negócio para capacidades de integração reutilizáveis, cobrindo valor, utilizadores, propriedade, envolvimento, custos e benefícios sem assumir disponibilização por API.", "category": "canvas", "icon": "dashboard-outline", "order": 3.1, "outcomes": [ "Modelo operacional viável para a capacidade reutilizável", "Propriedade, utilizadores, canais, parceiros e necessidades de suporte clarificados", "Custos e benefícios visíveis antes do compromisso com a arquitetura" ], "steps": [ "Resuma a proposta de valor da capacidade.", "Identifique segmentos de utilizadores e canais de envolvimento.", "Defina atividades, recursos e parceiros-chave.", "Capte custos e benefícios.", "Clarifique propriedade, financiamento, suporte e expectativas de ciclo de vida.", "Valide o modelo com utilizadores, produtores e partes interessadas de governação." ], "canvasId": "capabilityBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false } ], "promptIds": [ "integration-architect:facilitate-station", "integration-architect:use-resources", "integration-architect:next-actions" ] }, { "id": "platform-architect", "stakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "summary": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "stakeholder": { "id": "platform-architect", "sourceKey": "platform-architect", "sourceStakeholderId": "platform-architect", "title": "Arquiteto de plataforma", "description": "Orienta decisões de plataforma, integração, escalabilidade e arquitetura que moldam como a capacidade ou API é construída e operada.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." }, { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." }, { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." }, { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." }, { "id": "api-delivery", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia." }, { "id": "api-audit", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." } ], "canvases": [ { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "capabilityBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da Capacidade" }, { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" }, { "id": "interactionCanvas", "title": "Canvas de Interação" }, { "id": "apiValuePropositionCanvas", "title": "Canvas da Proposta de Valor da API" }, { "id": "apiBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da API" }, { "id": "restCanvas", "title": "Canvas REST" }, { "id": "eventCanvas", "title": "Canvas de Eventos" }, { "id": "graphqlCanvas", "title": "Canvas GraphQL" } ], "decisions": [ "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais." ], "outputs": [ "Uma proposta de valor e um público-alvo da API simples", "Linguagem partilhada entre o produto, a conceção e a tecnologia", "Um argumento sólido ou um caso para financiamento/aprovação", "design-artifact", "documentation", "research", "roadmap", "Corte APIs redundantes e reduza os custos da plataforma de nuvem" ], "recommendedResources": [ { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityBusinessModelCanvas", "slug": "resources/capability-business-model-canvas", "title": "Canvas do Modelo de Negócio da Capacidade", "description": "Um canvas de modelo de negócio para capacidades de integração reutilizáveis, cobrindo valor, utilizadores, propriedade, envolvimento, custos e benefícios sem assumir disponibilização por API.", "category": "canvas", "icon": "dashboard-outline", "order": 3.1, "outcomes": [ "Modelo operacional viável para a capacidade reutilizável", "Propriedade, utilizadores, canais, parceiros e necessidades de suporte clarificados", "Custos e benefícios visíveis antes do compromisso com a arquitetura" ], "steps": [ "Resuma a proposta de valor da capacidade.", "Identifique segmentos de utilizadores e canais de envolvimento.", "Defina atividades, recursos e parceiros-chave.", "Capte custos e benefícios.", "Clarifique propriedade, financiamento, suporte e expectativas de ciclo de vida.", "Valide o modelo com utilizadores, produtores e partes interessadas de governação." ], "canvasId": "capabilityBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "contract-first-design", "slug": "resources/contract-first-design", "title": "Primeira conceção do contrato", "description": "Uma diretriz que defende abordagens API-first utilizando contratos formais (por exemplo, OpenAPI) para alinhar as partes interessadas antes do desenvolvimento.", "category": "guideline", "icon": "edit-document-outline", "order": 146, "outcomes": [ "Melhor compreensão dos princípios de conceção da primeira fase do contrato", "Abordagem normalizada utilizando a conceção orientada por contrato", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar." ], "canvasId": null, "sourcePath": "src/snippets/api-contract-example.yaml", "sourceUrl": null, "contentMarkdown": "openapi: 3.0.3\r\ninfo:\r\n title: Sample Catalog API\r\n version: 1.0.0\r\n description: |\r\n Starter example for a read-only APIOps Cycles API.\r\n This example keeps the contract audit-friendly and easy to extend.\r\nservers:\r\n - url: /v1\r\n description: Versioned API base path\r\ntags:\r\n - name: catalog\r\n description: Browse and search catalog items\r\npaths:\r\n /items:\r\n get:\r\n tags: [catalog]\r\n summary: List catalog items\r\n description: Returns a paginated list of public catalog items.\r\n operationId: listItems\r\n parameters:\r\n - $ref: \"#/components/parameters/searchTerm\"\r\n - $ref: \"#/components/parameters/categoryId\"\r\n - $ref: \"#/components/parameters/page\"\r\n - $ref: \"#/components/parameters/pageSize\"\r\n responses:\r\n \"200\":\r\n description: Item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n examples:\r\n default:\r\n value:\r\n data:\r\n - itemId: item-123\r\n slug: blue-widget\r\n name: Blue Widget\r\n status: published\r\n page:\r\n number: 1\r\n size: 20\r\n totalItems: 1\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"429\":\r\n $ref: \"#/components/responses/TooManyRequests\"\r\n /items/{itemId}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by id\r\n description: Returns a single public catalog item by opaque identifier.\r\n operationId: getItemById\r\n parameters:\r\n - $ref: \"#/components/parameters/itemId\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /items/by-slug/{slug}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by slug\r\n description: Returns a single item by public slug.\r\n operationId: getItemBySlug\r\n parameters:\r\n - $ref: \"#/components/parameters/slug\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /categories/{categoryId}/items:\r\n get:\r\n tags: [catalog]\r\n summary: List items in category\r\n description: Returns public items in a category.\r\n operationId: listItemsByCategory\r\n parameters:\r\n - $ref: \"#/components/parameters/categoryId\"\r\n responses:\r\n \"200\":\r\n description: Category item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\ncomponents:\r\n parameters:\r\n itemId:\r\n name: itemId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: item-123\r\n slug:\r\n name: slug\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9]+(?:-[a-z0-9]+)*$\"\r\n example: blue-widget\r\n categoryId:\r\n name: categoryId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: home-goods\r\n searchTerm:\r\n name: searchTerm\r\n in: query\r\n required: false\r\n schema:\r\n type: string\r\n minLength: 1\r\n example: widget\r\n page:\r\n name: page\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n default: 1\r\n pageSize:\r\n name: pageSize\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n maximum: 100\r\n default: 20\r\n responses:\r\n BadRequest:\r\n description: Validation failed\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n examples:\r\n default:\r\n value:\r\n code: BAD_REQUEST\r\n message: Invalid request\r\n NotFound:\r\n description: Resource not found\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n TooManyRequests:\r\n description: Rate limit exceeded\r\n headers:\r\n Retry-After:\r\n schema:\r\n type: integer\r\n description: Seconds until the next allowed request.\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n schemas:\r\n ItemListResponse:\r\n type: object\r\n required: [data, page]\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/ItemSummary\"\r\n page:\r\n $ref: \"#/components/schemas/Page\"\r\n ItemSummary:\r\n type: object\r\n required: [itemId, slug, name, status]\r\n properties:\r\n itemId:\r\n type: string\r\n slug:\r\n type: string\r\n name:\r\n type: string\r\n status:\r\n type: string\r\n enum: [published, hidden]\r\n ItemDetail:\r\n allOf:\r\n - $ref: \"#/components/schemas/ItemSummary\"\r\n - type: object\r\n properties:\r\n description:\r\n type: string\r\n categories:\r\n type: array\r\n items:\r\n type: string\r\n variants:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/Variant\"\r\n Variant:\r\n type: object\r\n required: [variantId, sku, price, inventory]\r\n properties:\r\n variantId:\r\n type: string\r\n sku:\r\n type: string\r\n price:\r\n $ref: \"#/components/schemas/Price\"\r\n inventory:\r\n $ref: \"#/components/schemas/Inventory\"\r\n Price:\r\n type: object\r\n required: [amount, currency]\r\n properties:\r\n amount:\r\n type: number\r\n format: decimal\r\n currency:\r\n type: string\r\n example: EUR\r\n Inventory:\r\n type: object\r\n required: [available]\r\n properties:\r\n available:\r\n type: integer\r\n minimum: 0\r\n reserved:\r\n type: integer\r\n minimum: 0\r\n source:\r\n type: string\r\n Page:\r\n type: object\r\n required: [number, size, totalItems]\r\n properties:\r\n number:\r\n type: integer\r\n size:\r\n type: integer\r\n totalItems:\r\n type: integer\r\n ErrorResponse:\r\n type: object\r\n required: [code, message]\r\n properties:\r\n code:\r\n type: string\r\n message:\r\n type: string\r\n", "draft": true }, { "id": "api-development-best-practices", "slug": "resources/api-development-best-practices", "title": "Boas práticas de desenvolvimento de API", "description": "Orientações de implementação para transformar um contrato de interface da API validado numa base de código de API consistente e sustentável, utilizando bibliotecas padrão, padrões reutilizáveis e fluxos de trabalho de desenvolvimento alinhados.", "category": "guideline", "icon": "edit-document-outline", "order": 112, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de desenvolvimento de API", "Abordagem normalizada utilizando as boas práticas de desenvolvimento de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplique essas práticas ao contrato de interface da API validado e ao plano de implementação antes do início da codificação.", "Utilize frameworks, bibliotecas e padrões de codificação estabelecidos para implementar o contrato de forma consistente e sustentável." ], "canvasId": null, "sourcePath": "src/snippets/pt/api-design-principles-guidance.md", "sourceUrl": null, "contentMarkdown": "## Como iniciar o trabalho de entrega da API com base nas fases anteriores (“etapas”)\r\nUtilize estas orientações no início da `API Delivery` (entrega da API), após a revisão e aceitação do contrato da API (por exemplo, OpenAPI) e dos principais resultados das etapas anteriores.\r\nO objetivo não é desenvolver a implementação de forma isolada. O objetivo é transformar os resultados acordados nas etapas anteriores em uma estrutura de código concreta, regras de validação, comportamento em tempo de execução e decisões relativas à entrega do produto API.\r\n\r\n---\r\n\r\n### 1. Comece a partir do contrato validado\r\n- Trate o contrato de API validado como o principal ponto de referência para as decisões de implementação.\r\n- Mantenha o contrato e a implementação alinhados ao longo de toda a entrega do produto API.\r\n- Use o contrato para orientar a validação de solicitações, o mapeamento de respostas, a documentação e os testes.\r\n\r\n---\r\n\r\n### 2. Use os resultados do domínio para preservar o significado comercial\r\n- Use os resultados do `Domain Canvas` para orientar a nomenclatura, como a implementação é dividida em responsabilidades comerciais claras e como diferentes sistemas de back-end são conectados sem expor suas diferenças.\r\n- Preserve os significados validados de entidades, atributos, status e regras de fonte de verdade.\r\n- Evite vazar modelos específicos do back-end ou inconsistências para a API pública.\r\n\r\n---\r\n\r\n### 3. Use os resultados da jornada para preservar fluxos críticos\r\n- Use os resultados do `Customer Journey Canvas` para identificar quais fluxos de usuários são mais importantes para serem atendidos primeiro.\r\n- Use os resultados da `API Consumer Experience` para manter a API compreensível, previsível e fácil de integrar.\r\n- Deixe que as prioridades de jornada acordadas decidam quais caminhos de implementação precisam da maior confiabilidade, menor latência, erros mais claros e maior foco operacional.\r\n\r\n---\r\n\r\n### 4. Use os resultados da Proposta de Valor para preservar o valor para o consumidor\r\n- Use os resultados do `API Value Proposition Canvas` para manter a implementação focada nas dores, ganhos e recursos da API acordados.\r\n- Preserve os significados dos campos, o comportamento e as promessas que tornaram a API valiosa nas etapas anteriores.\r\n- Garanta que o tratamento de erros, a atualização e a nomenclatura apoiem tanto a experiência do desenvolvedor pretendida quanto o caso de uso de negócios.\r\n\r\n---\r\n\r\n### 5. Use os resultados da arquitetura para moldar as decisões de tempo de execução\r\n- Use os resultados do `Business Impact Canvas` para orientar as decisões sobre resiliência, tempo limite, fallback e degradação.\r\n- Use os resultados do `Locations Canvas` para orientar os limites de rede, limites de confiança, caminhos de acesso e restrições de implantação.\r\n- Use os resultados do `Capacity Canvas` para orientar limites de taxa, cache, escalonamento e comportamento em picos de carga.\r\n- Use as orientações do `API Metrics And Analytics` para decidir o que deve ser observado desde a primeira implementação em diante.\r\n\r\n---\r\n\r\n### 6. Use os resultados do projeto de interação e protocolo para moldar a estrutura do código\r\n- Use os resultados do `Interaction Canvas` para evitar implementar estilos de interação não suportados prematuramente.\r\n- Use os resultados do projeto `REST`, `Event` ou `GraphQL` para moldar o comportamento de solicitação, resposta e validação específico do protocolo.\r\n- Reflete o estilo de interação selecionado claramente na estrutura do código, nas responsabilidades e na estratégia de testes.\r\n\r\n---\r\n\r\n### 7. Usa os resultados da auditoria para melhorar a entrega antes que a codificação avance demais\r\n- Usa as conclusões da auditoria para remover ambiguidades antes que a implementação se espalhe pela base de código.\r\n- Corrige regras de solicitação pouco claras, validações ausentes, contratos de erro fracos e lacunas operacionais logo no início.\r\n- Trate a auditoria como um ciclo de melhoria de projeto antes da produção, não apenas como uma etapa de decisão final.\r\n\r\n---\r\n\r\n### 8. Aplique as orientações e, em seguida, resuma\r\n- Aplique estas orientações à API atual e ao plano de implementação.\r\n- Resuma as implicações para a estrutura do código, validação de solicitações, integração de fontes, segurança, monitoramento e alertas, e testes.\r\n- Não crie um artefato de entrega separado, a menos que a equipe ou o usuário precise especificamente de um.\r\n", "draft": true } ], "promptIds": [ "platform-architect:facilitate-station", "platform-architect:use-resources", "platform-architect:next-actions" ] }, { "id": "api-designer", "stakeholderId": "api-designer", "title": "Designer API", "summary": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "stakeholder": { "id": "api-designer", "sourceKey": "api-designer", "sourceStakeholderId": "api-designer", "title": "Designer API", "description": "Modela o contrato de interface, o modelo de interação, a consistência e a usabilidade das capacidades expostas.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." }, { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." }, { "id": "api-delivery", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia." }, { "id": "api-audit", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição." }, { "id": "api-consumer-experience", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento." } ], "canvases": [ { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "interactionCanvas", "title": "Canvas de Interação" }, { "id": "consumerExperienceRequirementsCanvas", "title": "Canvas de Requisitos da Experiência do Utilizador" }, { "id": "restCanvas", "title": "Canvas REST" }, { "id": "eventCanvas", "title": "Canvas de Eventos" }, { "id": "graphqlCanvas", "title": "Canvas GraphQL" }, { "id": "apiValuePropositionCanvas", "title": "Canvas da Proposta de Valor da API" }, { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" } ], "decisions": [ "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." ], "outputs": [ "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", "spec", "contract", "design-artifact", "documentation" ], "recommendedResources": [ { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "contract-first-design", "slug": "resources/contract-first-design", "title": "Primeira conceção do contrato", "description": "Uma diretriz que defende abordagens API-first utilizando contratos formais (por exemplo, OpenAPI) para alinhar as partes interessadas antes do desenvolvimento.", "category": "guideline", "icon": "edit-document-outline", "order": 146, "outcomes": [ "Melhor compreensão dos princípios de conceção da primeira fase do contrato", "Abordagem normalizada utilizando a conceção orientada por contrato", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar." ], "canvasId": null, "sourcePath": "src/snippets/api-contract-example.yaml", "sourceUrl": null, "contentMarkdown": "openapi: 3.0.3\r\ninfo:\r\n title: Sample Catalog API\r\n version: 1.0.0\r\n description: |\r\n Starter example for a read-only APIOps Cycles API.\r\n This example keeps the contract audit-friendly and easy to extend.\r\nservers:\r\n - url: /v1\r\n description: Versioned API base path\r\ntags:\r\n - name: catalog\r\n description: Browse and search catalog items\r\npaths:\r\n /items:\r\n get:\r\n tags: [catalog]\r\n summary: List catalog items\r\n description: Returns a paginated list of public catalog items.\r\n operationId: listItems\r\n parameters:\r\n - $ref: \"#/components/parameters/searchTerm\"\r\n - $ref: \"#/components/parameters/categoryId\"\r\n - $ref: \"#/components/parameters/page\"\r\n - $ref: \"#/components/parameters/pageSize\"\r\n responses:\r\n \"200\":\r\n description: Item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n examples:\r\n default:\r\n value:\r\n data:\r\n - itemId: item-123\r\n slug: blue-widget\r\n name: Blue Widget\r\n status: published\r\n page:\r\n number: 1\r\n size: 20\r\n totalItems: 1\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"429\":\r\n $ref: \"#/components/responses/TooManyRequests\"\r\n /items/{itemId}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by id\r\n description: Returns a single public catalog item by opaque identifier.\r\n operationId: getItemById\r\n parameters:\r\n - $ref: \"#/components/parameters/itemId\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /items/by-slug/{slug}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by slug\r\n description: Returns a single item by public slug.\r\n operationId: getItemBySlug\r\n parameters:\r\n - $ref: \"#/components/parameters/slug\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /categories/{categoryId}/items:\r\n get:\r\n tags: [catalog]\r\n summary: List items in category\r\n description: Returns public items in a category.\r\n operationId: listItemsByCategory\r\n parameters:\r\n - $ref: \"#/components/parameters/categoryId\"\r\n responses:\r\n \"200\":\r\n description: Category item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\ncomponents:\r\n parameters:\r\n itemId:\r\n name: itemId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: item-123\r\n slug:\r\n name: slug\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9]+(?:-[a-z0-9]+)*$\"\r\n example: blue-widget\r\n categoryId:\r\n name: categoryId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: home-goods\r\n searchTerm:\r\n name: searchTerm\r\n in: query\r\n required: false\r\n schema:\r\n type: string\r\n minLength: 1\r\n example: widget\r\n page:\r\n name: page\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n default: 1\r\n pageSize:\r\n name: pageSize\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n maximum: 100\r\n default: 20\r\n responses:\r\n BadRequest:\r\n description: Validation failed\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n examples:\r\n default:\r\n value:\r\n code: BAD_REQUEST\r\n message: Invalid request\r\n NotFound:\r\n description: Resource not found\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n TooManyRequests:\r\n description: Rate limit exceeded\r\n headers:\r\n Retry-After:\r\n schema:\r\n type: integer\r\n description: Seconds until the next allowed request.\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n schemas:\r\n ItemListResponse:\r\n type: object\r\n required: [data, page]\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/ItemSummary\"\r\n page:\r\n $ref: \"#/components/schemas/Page\"\r\n ItemSummary:\r\n type: object\r\n required: [itemId, slug, name, status]\r\n properties:\r\n itemId:\r\n type: string\r\n slug:\r\n type: string\r\n name:\r\n type: string\r\n status:\r\n type: string\r\n enum: [published, hidden]\r\n ItemDetail:\r\n allOf:\r\n - $ref: \"#/components/schemas/ItemSummary\"\r\n - type: object\r\n properties:\r\n description:\r\n type: string\r\n categories:\r\n type: array\r\n items:\r\n type: string\r\n variants:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/Variant\"\r\n Variant:\r\n type: object\r\n required: [variantId, sku, price, inventory]\r\n properties:\r\n variantId:\r\n type: string\r\n sku:\r\n type: string\r\n price:\r\n $ref: \"#/components/schemas/Price\"\r\n inventory:\r\n $ref: \"#/components/schemas/Inventory\"\r\n Price:\r\n type: object\r\n required: [amount, currency]\r\n properties:\r\n amount:\r\n type: number\r\n format: decimal\r\n currency:\r\n type: string\r\n example: EUR\r\n Inventory:\r\n type: object\r\n required: [available]\r\n properties:\r\n available:\r\n type: integer\r\n minimum: 0\r\n reserved:\r\n type: integer\r\n minimum: 0\r\n source:\r\n type: string\r\n Page:\r\n type: object\r\n required: [number, size, totalItems]\r\n properties:\r\n number:\r\n type: integer\r\n size:\r\n type: integer\r\n totalItems:\r\n type: integer\r\n ErrorResponse:\r\n type: object\r\n required: [code, message]\r\n properties:\r\n code:\r\n type: string\r\n message:\r\n type: string\r\n", "draft": true }, { "id": "api-development-best-practices", "slug": "resources/api-development-best-practices", "title": "Boas práticas de desenvolvimento de API", "description": "Orientações de implementação para transformar um contrato de interface da API validado numa base de código de API consistente e sustentável, utilizando bibliotecas padrão, padrões reutilizáveis e fluxos de trabalho de desenvolvimento alinhados.", "category": "guideline", "icon": "edit-document-outline", "order": 112, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de desenvolvimento de API", "Abordagem normalizada utilizando as boas práticas de desenvolvimento de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplique essas práticas ao contrato de interface da API validado e ao plano de implementação antes do início da codificação.", "Utilize frameworks, bibliotecas e padrões de codificação estabelecidos para implementar o contrato de forma consistente e sustentável." ], "canvasId": null, "sourcePath": "src/snippets/pt/api-design-principles-guidance.md", "sourceUrl": null, "contentMarkdown": "## Como iniciar o trabalho de entrega da API com base nas fases anteriores (“etapas”)\r\nUtilize estas orientações no início da `API Delivery` (entrega da API), após a revisão e aceitação do contrato da API (por exemplo, OpenAPI) e dos principais resultados das etapas anteriores.\r\nO objetivo não é desenvolver a implementação de forma isolada. O objetivo é transformar os resultados acordados nas etapas anteriores em uma estrutura de código concreta, regras de validação, comportamento em tempo de execução e decisões relativas à entrega do produto API.\r\n\r\n---\r\n\r\n### 1. Comece a partir do contrato validado\r\n- Trate o contrato de API validado como o principal ponto de referência para as decisões de implementação.\r\n- Mantenha o contrato e a implementação alinhados ao longo de toda a entrega do produto API.\r\n- Use o contrato para orientar a validação de solicitações, o mapeamento de respostas, a documentação e os testes.\r\n\r\n---\r\n\r\n### 2. Use os resultados do domínio para preservar o significado comercial\r\n- Use os resultados do `Domain Canvas` para orientar a nomenclatura, como a implementação é dividida em responsabilidades comerciais claras e como diferentes sistemas de back-end são conectados sem expor suas diferenças.\r\n- Preserve os significados validados de entidades, atributos, status e regras de fonte de verdade.\r\n- Evite vazar modelos específicos do back-end ou inconsistências para a API pública.\r\n\r\n---\r\n\r\n### 3. Use os resultados da jornada para preservar fluxos críticos\r\n- Use os resultados do `Customer Journey Canvas` para identificar quais fluxos de usuários são mais importantes para serem atendidos primeiro.\r\n- Use os resultados da `API Consumer Experience` para manter a API compreensível, previsível e fácil de integrar.\r\n- Deixe que as prioridades de jornada acordadas decidam quais caminhos de implementação precisam da maior confiabilidade, menor latência, erros mais claros e maior foco operacional.\r\n\r\n---\r\n\r\n### 4. Use os resultados da Proposta de Valor para preservar o valor para o consumidor\r\n- Use os resultados do `API Value Proposition Canvas` para manter a implementação focada nas dores, ganhos e recursos da API acordados.\r\n- Preserve os significados dos campos, o comportamento e as promessas que tornaram a API valiosa nas etapas anteriores.\r\n- Garanta que o tratamento de erros, a atualização e a nomenclatura apoiem tanto a experiência do desenvolvedor pretendida quanto o caso de uso de negócios.\r\n\r\n---\r\n\r\n### 5. Use os resultados da arquitetura para moldar as decisões de tempo de execução\r\n- Use os resultados do `Business Impact Canvas` para orientar as decisões sobre resiliência, tempo limite, fallback e degradação.\r\n- Use os resultados do `Locations Canvas` para orientar os limites de rede, limites de confiança, caminhos de acesso e restrições de implantação.\r\n- Use os resultados do `Capacity Canvas` para orientar limites de taxa, cache, escalonamento e comportamento em picos de carga.\r\n- Use as orientações do `API Metrics And Analytics` para decidir o que deve ser observado desde a primeira implementação em diante.\r\n\r\n---\r\n\r\n### 6. Use os resultados do projeto de interação e protocolo para moldar a estrutura do código\r\n- Use os resultados do `Interaction Canvas` para evitar implementar estilos de interação não suportados prematuramente.\r\n- Use os resultados do projeto `REST`, `Event` ou `GraphQL` para moldar o comportamento de solicitação, resposta e validação específico do protocolo.\r\n- Reflete o estilo de interação selecionado claramente na estrutura do código, nas responsabilidades e na estratégia de testes.\r\n\r\n---\r\n\r\n### 7. Usa os resultados da auditoria para melhorar a entrega antes que a codificação avance demais\r\n- Usa as conclusões da auditoria para remover ambiguidades antes que a implementação se espalhe pela base de código.\r\n- Corrige regras de solicitação pouco claras, validações ausentes, contratos de erro fracos e lacunas operacionais logo no início.\r\n- Trate a auditoria como um ciclo de melhoria de projeto antes da produção, não apenas como uma etapa de decisão final.\r\n\r\n---\r\n\r\n### 8. Aplique as orientações e, em seguida, resuma\r\n- Aplique estas orientações à API atual e ao plano de implementação.\r\n- Resuma as implicações para a estrutura do código, validação de solicitações, integração de fontes, segurança, monitoramento e alertas, e testes.\r\n- Não crie um artefato de entrega separado, a menos que a equipe ou o usuário precise especificamente de um.\r\n", "draft": true }, { "id": "api-testing-best-practices", "slug": "resources/api-testing-best-practices", "title": "Boas práticas de teste de API", "description": "Diretrizes para a implementação de testes automatizados funcionais, de desempenho e de segurança ao longo do ciclo de vida da API.", "category": "guideline", "icon": "edit-document-outline", "order": 133, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de teste de API", "Abordagem normalizada utilizando as boas práticas de teste de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Integrar testes funcionais e não funcionais no pipeline CI/CD para garantir que as APIs cumprems normas de qualidade.", "Utilizar ferramentas de teste automatizadas para validar a funcionalidade, a segurança e o desempenho da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "apiops-CI-CD-for-apis", "slug": "resources/apiops-CI-CD-for-apis", "title": "APIOps CI/CD para APIs", "description": "Orientação de disponibilização que integra tarefas do ciclo de vida da API - design, teste, governação - em pipelines de integração e entrega contínuas.", "category": "guideline", "icon": "edit-document-outline", "order": 140, "outcomes": [ "Melhor compreensão dos princípios de CI/CD para APIs", "Abordagem normalizada utilizando CI/CD para APIs", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilizar pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-audit-checklist", "slug": "resources/api-audit-checklist", "title": "Lista de verificação de auditoria da API", "description": "Uma lista de verificação baseada no ciclo de vida para verificar a prontidão da API em design, entrega, publicação e conformidade utilizando critérios de auditoria e evidências definidos.", "category": "checklist", "icon": "check-box-outline", "order": 13, "outcomes": [ "Melhor compreensão dos princípios da lista de controlo de auditoria da API", "Abordagem normalizada utilizando a lista de verificação de auditoria da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilize a lista de verificação de auditoria da API para garantir que a conceção da API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Realize auditorias para avaliar a cobertura do ciclo de vida e verificar se a API satisfaz os padrões de negócio, conceção e operacionais.", "Certifique-se de que a documentação, os modelos de segurança, a configuração do gateway e os requisitos legais estejam claramente definidos, validados e comprovados por evidências." ], "canvasId": null, "sourcePath": "src/snippets/api-audit-checklist.json", "sourceUrl": null, "contentMarkdown": "{\r\n \"profiles\": {\r\n \"read-only\": {\r\n \"description\": \"API profile that is read-only and does not allow create, update, or delete operations.\"\r\n },\r\n \"full-crud\": {\r\n \"description\": \"General API profile that allows create, update, and delete operations.\"\r\n }\r\n },\r\n \"lifecycleStages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6\r\n }\r\n ],\r\n \"stages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1,\r\n \"items\": [\r\n {\r\n \"id\": \"based-on-clear-business-needs\",\r\n \"label\": \"API is based on clear business needs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiBusinessModelCanvas\",\r\n \"apiValuePropositionCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"design-artifact\",\r\n \"documentation\",\r\n \"research\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\",\r\n \"specs/canvases/api-product-strategy/apiBusinessModelCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"concept-items-audited\",\r\n \"label\": \"All concept checklist items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"strategy\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\",\r\n \"api-opportunity-documented\",\r\n \"api-reusability\",\r\n \"value-prop-validated\",\r\n \"consumer-segments-identified\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/concept-review-report.json\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2,\r\n \"items\": [\r\n {\r\n \"id\": \"versioning-decided\",\r\n \"label\": \"Versioning strategy decided and supported by gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VERSION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-versioning-best-practices\",\r\n \"apiops-CI-CD-for-apis\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"ci-cd\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"only-via-gateway\",\r\n \"label\": \"Only accessible via API gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-02\",\r\n \"REST-CAPACITY-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"businessImpactCanvas\",\r\n \"locationsCanvas\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"infra-config\",\r\n \"security-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"rate-limits-enforced\",\r\n \"label\": \"Rate limits are enforced\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CAPACITY-01\",\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"capacityCanvas\",\r\n \"api-security-best-practices\",\r\n \"scalable-infrastructure-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"runtime\",\r\n \"monitoring\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-platform-architecture/capacityCanvas.empty.json\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3,\r\n \"items\": [\r\n {\r\n \"id\": \"endpoint-descriptions-present\",\r\n \"label\": \"Endpoints have business value and feature descriptions\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"operationDescriptions\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\",\r\n \"api-opportunity-documented\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiValuePropositionCanvas\",\r\n \"customerJourneyCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"hides-raw-backend-data\",\r\n \"label\": \"API hides raw backend data and is designed for shared use\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"interactionCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/domainCanvas.empty.json\",\r\n \"specs/canvases/api-design/interactionCanvas.empty.json\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"design-consistent\",\r\n \"label\": \"API design is consistent with other APIs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-02\",\r\n \"REST-CX-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-design/restCanvas.empty.json\",\r\n \"docs/api/design/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"descriptive-english-naming\",\r\n \"label\": \"Data and attribute naming uses descriptive English\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"fieldNamesDescriptive\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"mandatory-fields-specified\",\r\n \"label\": \"Mandatory fields are specified\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"requiredFieldsPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"dates-use-iso\",\r\n \"label\": \"Dates use ISO format with timezone\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"dateFormatTimezone\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"general-data-uses-standard-values\",\r\n \"label\": \"General data uses standard values\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"standardizedEnumsOrPatterns\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"field-names-avoid-acronyms\",\r\n \"label\": \"Field names avoid acronyms and use full words\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"avoidAcronyms\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"create-returns-identifiers\",\r\n \"label\": \"Creating new resources returns identifiers\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is read-only and does not create resources.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"paths-max-two-resources\",\r\n \"label\": \"Endpoint paths contain max two resources or sub-resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"pathDepthMax\",\r\n \"maxDepth\": 2\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PATH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"examples-present\",\r\n \"label\": \"Endpoints and attributes include examples\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-for-create-update\",\r\n \"label\": \"POST is used for create or update\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose create or update operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-for-remove\",\r\n \"label\": \"DELETE is used to remove resources\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose delete operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-no-request-body\",\r\n \"label\": \"GET has no request body and returns content\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"getNoRequestBody\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-empty-returns-204\",\r\n \"label\": \"GET returns 204 if response body is empty\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current contract returns content for all GET operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-200\",\r\n \"label\": \"POST returns 200 OK when updating\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST updates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-201\",\r\n \"label\": \"POST returns 201 Created with ID on create\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST creates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-returns-204\",\r\n \"label\": \"DELETE returns 204 on success\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose DELETE operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"400-errors-specific\",\r\n \"label\": \"400 errors provide specific error information\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"errorResponsesSpecific\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-400-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"api-audit-checklist\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"401-unauthorized\",\r\n \"label\": \"401 Unauthorized for wrong credentials\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current public storefront contract is intentionally unauthenticated.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-401-01\",\r\n \"REST-SEC-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"403-forbidden\",\r\n \"label\": \"403 Forbidden for unauthorized operations\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current profile is public read-only and exposes no unauthorized operations.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-403-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-contains-schemas\",\r\n \"label\": \"Spec contains request and response schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"schemasPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"restCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"pseudo-identifiers\",\r\n \"label\": \"UUIDs or pseudo-identifiers instead of DB IDs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"opaqueIdentifiers\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-07\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"no-sensitive-data-in-urls\",\r\n \"label\": \"No sensitive data in URLs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"noSensitiveDataInPaths\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-06\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"http-methods-match-resources\",\r\n \"label\": \"HTTP methods only for intended resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"methodResourceConsistency\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\",\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4,\r\n \"items\": [\r\n {\r\n \"id\": \"design-items-audited\",\r\n \"label\": \"All prototype and design items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"design\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"design-reflects-business-value\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/production-readiness-review.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-validated-on-change\",\r\n \"label\": \"Spec validated on every change\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"validationWorkflowPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\",\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"schema-and-examples-pass\",\r\n \"label\": \"Schema and examples pass validation\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPassValidation\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-contract-tested\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\",\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"api-audit-checklist\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"uses-https\",\r\n \"label\": \"Uses HTTPS or encrypted protocols\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"auth-protection\",\r\n \"label\": \"Endpoints protected by authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"token-auth\",\r\n \"label\": \"Token-based authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"csrf-protection\",\r\n \"label\": \"Protected against CSRF\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-08\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-development-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"inputs-auto-validated\",\r\n \"label\": \"Inputs auto-validated by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"contract-first-design\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\",\r\n \"test\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"outputs-auto-escaped\",\r\n \"label\": \"Outputs auto-escaped by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"JSON APIs do not typically require output escaping in the same way as HTML rendering.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"encryption-in-transit\",\r\n \"label\": \"Encryption for data in transit and storage\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"infra-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"message-integrity\",\r\n \"label\": \"Message integrity implemented\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"monitoring\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5,\r\n \"items\": [\r\n {\r\n \"id\": \"published-via-api-management\",\r\n \"label\": \"Published via API management\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"ci-cd\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"visible-in-dev-portal\",\r\n \"label\": \"Visible in developer portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-community-engagement-strategies\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"docs-auto-generated\",\r\n \"label\": \"Docs auto-generated from spec and schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\",\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"documentation\",\r\n \"ci-cd\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/publishing/README.md\",\r\n \"docs/api/audit/design-audit.read-only.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-auto-updated\",\r\n \"label\": \"Spec auto-updated to gateway and dev portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"contract-first-design\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"gateway-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"official-domain\",\r\n \"label\": \"Published under official organization domain\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6,\r\n \"items\": []\r\n }\r\n ],\r\n \"guidelines\": [\r\n {\r\n \"id\": \"REST-CONTRACT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST implement endpoints, parameters, request bodies, response bodies, and error responses as defined in the validated OpenAPI contract.\",\r\n \"relatedAuditItems\": [\r\n \"spec-contains-schemas\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CONTRACT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST keep the implementation, published OpenAPI description, gateway configuration, and developer portal documentation aligned on every change.\",\r\n \"relatedAuditItems\": [\r\n \"docs-auto-generated\",\r\n \"spec-auto-updated\",\r\n \"spec-validated-on-change\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VALIDATION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate path parameters, query parameters, headers, and JSON request bodies against the OpenAPI schema before business processing.\",\r\n \"relatedAuditItems\": [\r\n \"mandatory-fields-specified\",\r\n \"400-errors-specific\",\r\n \"inputs-auto-validated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST expose business-oriented resources and attributes rather than raw backend tables, internal service payloads, or system-specific field names.\",\r\n \"relatedAuditItems\": [\r\n \"based-on-clear-business-needs\",\r\n \"hides-raw-backend-data\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST preserve validated meanings of entities, attributes, statuses, and source-of-truth rules across all endpoints and operations.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\",\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use descriptive English names for resources and attributes.\",\r\n \"relatedAuditItems\": [\r\n \"descriptive-english-naming\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST avoid unexplained acronyms in public field and resource names.\",\r\n \"relatedAuditItems\": [\r\n \"field-names-avoid-acronyms\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use ISO date-time values with timezone information where dates are exposed.\",\r\n \"relatedAuditItems\": [\r\n \"dates-use-iso\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API SHOULD use standard codes, controlled vocabularies, and standardized value sets where applicable.\",\r\n \"relatedAuditItems\": [\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST describe the business value and feature intent of each endpoint or capability.\",\r\n \"relatedAuditItems\": [\r\n \"endpoint-descriptions-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST include examples for endpoints, request bodies, response bodies, and key attributes.\",\r\n \"relatedAuditItems\": [\r\n \"examples-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API SHOULD use consistent pagination, filtering, sorting, and response conventions across resources.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-GET-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use GET for safe read-only operations and MUST NOT define a request body for GET operations.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-POST-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use POST for resource creation and other non-idempotent operations.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-PUT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use PUT only for full resource replacement.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-DELETE-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use DELETE to remove resources.\",\r\n \"relatedAuditItems\": [\r\n \"delete-for-remove\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PATH-01\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"resource-modeling\",\r\n \"requirement\": \"The REST API SHOULD keep endpoint paths shallow and avoid more than two resource or sub-resource levels unless explicitly justified.\",\r\n \"relatedAuditItems\": [\r\n \"paths-max-two-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-200-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 200 OK for successful reads and updates that include a response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"post-returns-200\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-201-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 201 Created and the created resource identifier when a new resource is created.\",\r\n \"relatedAuditItems\": [\r\n \"create-returns-identifiers\",\r\n \"post-returns-201\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 204 No Content for successful delete operations that do not return a body.\",\r\n \"relatedAuditItems\": [\r\n \"delete-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API SHOULD return 204 No Content for successful operations that intentionally return no response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-empty-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-400-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST define 400 Bad Request responses with specific and actionable validation error information.\",\r\n \"relatedAuditItems\": [\r\n \"400-errors-specific\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-401-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 401 Unauthorized for missing or invalid credentials.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-403-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 403 Forbidden for authenticated clients lacking sufficient permission.\",\r\n \"relatedAuditItems\": [\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VERSION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"versioning\",\r\n \"requirement\": \"The REST API MUST define a versioning strategy before production release, and the strategy MUST be supportable by the API gateway.\",\r\n \"relatedAuditItems\": [\r\n \"versioning-decided\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST require authentication for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use token-based authentication or another approved modern authentication mechanism for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"token-auth\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-03\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST enforce object-level and function-level authorization on every protected operation.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\",\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST mitigate OWASP API risks including broken object level authorization, broken function level authorization, injection, and unrestricted resource consumption.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"rate-limits-enforced\",\r\n \"no-sensitive-data-in-urls\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-05\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use HTTPS or another approved encrypted protocol for all traffic.\",\r\n \"relatedAuditItems\": [\r\n \"uses-https\",\r\n \"encryption-in-transit\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-06\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST NOT expose sensitive information in URLs, query strings, logs, or unnecessary response fields.\",\r\n \"relatedAuditItems\": [\r\n \"no-sensitive-data-in-urls\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-07\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API SHOULD use UUIDs or other non-sequential public identifiers where direct database identifiers would increase exposure risk.\",\r\n \"relatedAuditItems\": [\r\n \"pseudo-identifiers\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-08\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST implement CSRF protection where relevant to the authentication model and client interaction pattern.\",\r\n \"relatedAuditItems\": [\r\n \"csrf-protection\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST define and enforce rate limits, throttling, or quotas according to capacity expectations.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST implement resilience controls such as timeouts, fallback behavior, and degradation handling according to business impact.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-OBS-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"observability\",\r\n \"requirement\": \"The REST API MUST implement logs, metrics, and monitoring needed to observe validation failures, auth failures, traffic, latency, and dependency health.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published through an API management platform.\",\r\n \"relatedAuditItems\": [\r\n \"published-via-api-management\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be accessible only through approved API gateway paths and managed entry points.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API SHOULD be visible in a developer portal with documentation generated from the contract.\",\r\n \"relatedAuditItems\": [\r\n \"visible-in-dev-portal\",\r\n \"docs-auto-generated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published under an approved organizational domain.\",\r\n \"relatedAuditItems\": [\r\n \"official-domain\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate the specification, schema, and examples on every change.\",\r\n \"relatedAuditItems\": [\r\n \"spec-validated-on-change\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST pass concept, design, security, and production-readiness checks before release.\",\r\n \"relatedAuditItems\": [\r\n \"concept-items-audited\",\r\n \"design-items-audited\"\r\n ]\r\n }\r\n ]\r\n}\r\n", "draft": false }, { "id": "api-compliance-best-practices", "slug": "resources/api-compliance-best-practices", "title": "Boas práticas de conformidade da API", "description": "Garantir que as APIs cumprem conformidade legal, regulamentar e interna através de documentação, controlos e validações automatizadas.", "category": "guideline", "icon": "edit-document-outline", "order": 104, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de conformidade da API", "Abordagem normalizada utilizando as Melhores Práticas de Conformidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Documentar as medidas de conformidade e garantir que são comunicadas às partes interessadas e aos utilizadores.", "Implementar medidas para garantir que as APIs cumprem estes requisitos, incluindo encriptação de dados, controlos de acesso e pistas de auditoria.", "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "promptIds": [ "api-designer:facilitate-station", "api-designer:use-resources", "api-designer:next-actions" ] }, { "id": "automation-engineer", "stakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "summary": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "stakeholder": { "id": "automation-engineer", "sourceKey": "automation-engineer", "sourceStakeholderId": "automation-engineer", "title": "Engenheiro de automatização", "description": "Implementa, testa, integra e mantém soluções de automatização e workflows de suporte.", "involvement": "" }, "cycles": [ { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." }, { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." }, { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." }, { "id": "api-delivery", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia." }, { "id": "api-audit", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição." }, { "id": "api-publishing", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." } ], "canvases": [ { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" }, { "id": "interactionCanvas", "title": "Canvas de Interação" } ], "decisions": [ "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais." ], "outputs": [ "Uma proposta de valor e um público-alvo da API simples", "Linguagem partilhada entre o produto, a conceção e a tecnologia", "Um argumento sólido ou um caso para financiamento/aprovação", "design-artifact", "documentation", "research", "roadmap", "Corte APIs redundantes e reduza os custos da plataforma de nuvem" ], "recommendedResources": [ { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "automation-operational-ownership-guide", "slug": "resources/automation-operational-ownership-guide", "title": "Guia de responsabilidade operacional da automatização", "description": "Orientação para definir responsabilidade, runbooks, supervisão, suporte, monitorização, controlo de alterações e responsabilidades de melhoria contínua para automatizações.", "category": "guideline", "icon": "edit-document-outline", "order": 185, "outcomes": [ "Modelo operacional claro para a automatização", "Responsabilidades de propriedade, suporte e escalamento atribuídas", "Práticas de monitorização e alteração prontas para operação em produção" ], "steps": [ "Defina responsáveis de negócio, técnicos e operacionais pela automatização.", "Documente runbooks, caminhos de suporte, sinais de monitorização, expectativas de serviço e regras de escalamento.", "Defina controlo de alterações e práticas de revisão para atualizações de workflow, plataforma e regras." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "process-workflow-design-guide", "slug": "resources/process-workflow-design-guide", "title": "Guia de desenho do processo e workflow", "description": "Orientação para modelar passos do processo, papéis, passagens de responsabilidade, pontos de decisão, estados, entradas, saídas e exceções que moldam um workflow de automatização.", "category": "guideline", "icon": "edit-document-outline", "order": 181, "outcomes": [ "Desenho claro do workflow de automatização", "Passos do processo e passagens de responsabilidade documentados antes da implementação", "Estados do workflow, entradas, saídas e caminhos de exceção compreendidos" ], "steps": [ "Mapeie o fluxo do processo atual e alvo, incluindo responsabilidades humanas e dos sistemas.", "Identifique gatilhos do workflow, estados, decisões, entradas de dados, saídas e critérios de conclusão.", "Documente passagens de responsabilidade entre utilizadores, sistemas, operações e papéis de suporte.", "Confirme que passos devem ser automatizados e quais exigem julgamento humano." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "decision-business-rules-guide", "slug": "resources/decision-business-rules-guide", "title": "Guia de decisões e regras de negócio", "description": "Orientação para captar regras, limiares, decisões, aprovações, verificações de elegibilidade e responsabilidade pelas regras no desenho de automatizações.", "category": "guideline", "icon": "edit-document-outline", "order": 182, "outcomes": [ "Decisões e regras de negócio explícitas", "Regras e limiares documentados com responsáveis", "Decisões da automatização rastreáveis a políticas, processos ou intenção de negócio" ], "steps": [ "Liste as decisões que a automatização deve tomar ou apoiar.", "Documente condições das regras, limiares, exceções, aprovações e pontos de escalamento.", "Identifique responsáveis pelas regras e governação de alterações para cada área de decisão." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "promptIds": [ "automation-engineer:facilitate-station", "automation-engineer:use-resources", "automation-engineer:next-actions" ] }, { "id": "api-engineer", "stakeholderId": "api-engineer", "title": "Engenheiro de entrega", "summary": "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.", "stakeholder": { "id": "api-engineer", "sourceKey": "api-engineer", "sourceStakeholderId": "api-engineer", "title": "Engenheiro de entrega", "description": "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.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." }, { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-delivery", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia." }, { "id": "api-audit", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição." }, { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." }, { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." }, { "id": "api-publishing", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." } ], "canvases": [ { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "interactionCanvas", "title": "Canvas de Interação" }, { "id": "restCanvas", "title": "Canvas REST" }, { "id": "eventCanvas", "title": "Canvas de Eventos" }, { "id": "graphqlCanvas", "title": "Canvas GraphQL" } ], "decisions": [ "Utilize as Melhores Práticas de Desenvolvimento de API como orientação para implementar o contrato validado com frameworks e bibliotecas estabelecidos, garantindo que o resultado seja reutilizável e sustentável.", "Construa a implementação da API a partir do contrato validado usando frameworks, bibliotecas e padrões da equipa estabelecidos.", "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Utilize pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "Utilize a lista de verificação de auditoria da API para garantir que a API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade." ], "outputs": [ "APIs implementadas utilizando estruturas e padrões testados", "Pipelines de CI/CD fiáveis e automatizados", "Testes funcionais e não funcionais integrados", "Condutas de entrega seguras e conformes", "implementation", "pipeline-config", "test-report", "security-report" ], "recommendedResources": [ { "id": "api-development-best-practices", "slug": "resources/api-development-best-practices", "title": "Boas práticas de desenvolvimento de API", "description": "Orientações de implementação para transformar um contrato de interface da API validado numa base de código de API consistente e sustentável, utilizando bibliotecas padrão, padrões reutilizáveis e fluxos de trabalho de desenvolvimento alinhados.", "category": "guideline", "icon": "edit-document-outline", "order": 112, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de desenvolvimento de API", "Abordagem normalizada utilizando as boas práticas de desenvolvimento de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplique essas práticas ao contrato de interface da API validado e ao plano de implementação antes do início da codificação.", "Utilize frameworks, bibliotecas e padrões de codificação estabelecidos para implementar o contrato de forma consistente e sustentável." ], "canvasId": null, "sourcePath": "src/snippets/pt/api-design-principles-guidance.md", "sourceUrl": null, "contentMarkdown": "## Como iniciar o trabalho de entrega da API com base nas fases anteriores (“etapas”)\r\nUtilize estas orientações no início da `API Delivery` (entrega da API), após a revisão e aceitação do contrato da API (por exemplo, OpenAPI) e dos principais resultados das etapas anteriores.\r\nO objetivo não é desenvolver a implementação de forma isolada. O objetivo é transformar os resultados acordados nas etapas anteriores em uma estrutura de código concreta, regras de validação, comportamento em tempo de execução e decisões relativas à entrega do produto API.\r\n\r\n---\r\n\r\n### 1. Comece a partir do contrato validado\r\n- Trate o contrato de API validado como o principal ponto de referência para as decisões de implementação.\r\n- Mantenha o contrato e a implementação alinhados ao longo de toda a entrega do produto API.\r\n- Use o contrato para orientar a validação de solicitações, o mapeamento de respostas, a documentação e os testes.\r\n\r\n---\r\n\r\n### 2. Use os resultados do domínio para preservar o significado comercial\r\n- Use os resultados do `Domain Canvas` para orientar a nomenclatura, como a implementação é dividida em responsabilidades comerciais claras e como diferentes sistemas de back-end são conectados sem expor suas diferenças.\r\n- Preserve os significados validados de entidades, atributos, status e regras de fonte de verdade.\r\n- Evite vazar modelos específicos do back-end ou inconsistências para a API pública.\r\n\r\n---\r\n\r\n### 3. Use os resultados da jornada para preservar fluxos críticos\r\n- Use os resultados do `Customer Journey Canvas` para identificar quais fluxos de usuários são mais importantes para serem atendidos primeiro.\r\n- Use os resultados da `API Consumer Experience` para manter a API compreensível, previsível e fácil de integrar.\r\n- Deixe que as prioridades de jornada acordadas decidam quais caminhos de implementação precisam da maior confiabilidade, menor latência, erros mais claros e maior foco operacional.\r\n\r\n---\r\n\r\n### 4. Use os resultados da Proposta de Valor para preservar o valor para o consumidor\r\n- Use os resultados do `API Value Proposition Canvas` para manter a implementação focada nas dores, ganhos e recursos da API acordados.\r\n- Preserve os significados dos campos, o comportamento e as promessas que tornaram a API valiosa nas etapas anteriores.\r\n- Garanta que o tratamento de erros, a atualização e a nomenclatura apoiem tanto a experiência do desenvolvedor pretendida quanto o caso de uso de negócios.\r\n\r\n---\r\n\r\n### 5. Use os resultados da arquitetura para moldar as decisões de tempo de execução\r\n- Use os resultados do `Business Impact Canvas` para orientar as decisões sobre resiliência, tempo limite, fallback e degradação.\r\n- Use os resultados do `Locations Canvas` para orientar os limites de rede, limites de confiança, caminhos de acesso e restrições de implantação.\r\n- Use os resultados do `Capacity Canvas` para orientar limites de taxa, cache, escalonamento e comportamento em picos de carga.\r\n- Use as orientações do `API Metrics And Analytics` para decidir o que deve ser observado desde a primeira implementação em diante.\r\n\r\n---\r\n\r\n### 6. Use os resultados do projeto de interação e protocolo para moldar a estrutura do código\r\n- Use os resultados do `Interaction Canvas` para evitar implementar estilos de interação não suportados prematuramente.\r\n- Use os resultados do projeto `REST`, `Event` ou `GraphQL` para moldar o comportamento de solicitação, resposta e validação específico do protocolo.\r\n- Reflete o estilo de interação selecionado claramente na estrutura do código, nas responsabilidades e na estratégia de testes.\r\n\r\n---\r\n\r\n### 7. Usa os resultados da auditoria para melhorar a entrega antes que a codificação avance demais\r\n- Usa as conclusões da auditoria para remover ambiguidades antes que a implementação se espalhe pela base de código.\r\n- Corrige regras de solicitação pouco claras, validações ausentes, contratos de erro fracos e lacunas operacionais logo no início.\r\n- Trate a auditoria como um ciclo de melhoria de projeto antes da produção, não apenas como uma etapa de decisão final.\r\n\r\n---\r\n\r\n### 8. Aplique as orientações e, em seguida, resuma\r\n- Aplique estas orientações à API atual e ao plano de implementação.\r\n- Resuma as implicações para a estrutura do código, validação de solicitações, integração de fontes, segurança, monitoramento e alertas, e testes.\r\n- Não crie um artefato de entrega separado, a menos que a equipe ou o usuário precise especificamente de um.\r\n", "draft": true }, { "id": "api-testing-best-practices", "slug": "resources/api-testing-best-practices", "title": "Boas práticas de teste de API", "description": "Diretrizes para a implementação de testes automatizados funcionais, de desempenho e de segurança ao longo do ciclo de vida da API.", "category": "guideline", "icon": "edit-document-outline", "order": 133, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de teste de API", "Abordagem normalizada utilizando as boas práticas de teste de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Integrar testes funcionais e não funcionais no pipeline CI/CD para garantir que as APIs cumprems normas de qualidade.", "Utilizar ferramentas de teste automatizadas para validar a funcionalidade, a segurança e o desempenho da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "apiops-CI-CD-for-apis", "slug": "resources/apiops-CI-CD-for-apis", "title": "APIOps CI/CD para APIs", "description": "Orientação de disponibilização que integra tarefas do ciclo de vida da API - design, teste, governação - em pipelines de integração e entrega contínuas.", "category": "guideline", "icon": "edit-document-outline", "order": 140, "outcomes": [ "Melhor compreensão dos princípios de CI/CD para APIs", "Abordagem normalizada utilizando CI/CD para APIs", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilizar pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-audit-checklist", "slug": "resources/api-audit-checklist", "title": "Lista de verificação de auditoria da API", "description": "Uma lista de verificação baseada no ciclo de vida para verificar a prontidão da API em design, entrega, publicação e conformidade utilizando critérios de auditoria e evidências definidos.", "category": "checklist", "icon": "check-box-outline", "order": 13, "outcomes": [ "Melhor compreensão dos princípios da lista de controlo de auditoria da API", "Abordagem normalizada utilizando a lista de verificação de auditoria da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilize a lista de verificação de auditoria da API para garantir que a conceção da API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Realize auditorias para avaliar a cobertura do ciclo de vida e verificar se a API satisfaz os padrões de negócio, conceção e operacionais.", "Certifique-se de que a documentação, os modelos de segurança, a configuração do gateway e os requisitos legais estejam claramente definidos, validados e comprovados por evidências." ], "canvasId": null, "sourcePath": "src/snippets/api-audit-checklist.json", "sourceUrl": null, "contentMarkdown": "{\r\n \"profiles\": {\r\n \"read-only\": {\r\n \"description\": \"API profile that is read-only and does not allow create, update, or delete operations.\"\r\n },\r\n \"full-crud\": {\r\n \"description\": \"General API profile that allows create, update, and delete operations.\"\r\n }\r\n },\r\n \"lifecycleStages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6\r\n }\r\n ],\r\n \"stages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1,\r\n \"items\": [\r\n {\r\n \"id\": \"based-on-clear-business-needs\",\r\n \"label\": \"API is based on clear business needs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiBusinessModelCanvas\",\r\n \"apiValuePropositionCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"design-artifact\",\r\n \"documentation\",\r\n \"research\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\",\r\n \"specs/canvases/api-product-strategy/apiBusinessModelCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"concept-items-audited\",\r\n \"label\": \"All concept checklist items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"strategy\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\",\r\n \"api-opportunity-documented\",\r\n \"api-reusability\",\r\n \"value-prop-validated\",\r\n \"consumer-segments-identified\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/concept-review-report.json\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2,\r\n \"items\": [\r\n {\r\n \"id\": \"versioning-decided\",\r\n \"label\": \"Versioning strategy decided and supported by gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VERSION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-versioning-best-practices\",\r\n \"apiops-CI-CD-for-apis\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"ci-cd\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"only-via-gateway\",\r\n \"label\": \"Only accessible via API gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-02\",\r\n \"REST-CAPACITY-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"businessImpactCanvas\",\r\n \"locationsCanvas\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"infra-config\",\r\n \"security-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"rate-limits-enforced\",\r\n \"label\": \"Rate limits are enforced\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CAPACITY-01\",\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"capacityCanvas\",\r\n \"api-security-best-practices\",\r\n \"scalable-infrastructure-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"runtime\",\r\n \"monitoring\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-platform-architecture/capacityCanvas.empty.json\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3,\r\n \"items\": [\r\n {\r\n \"id\": \"endpoint-descriptions-present\",\r\n \"label\": \"Endpoints have business value and feature descriptions\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"operationDescriptions\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\",\r\n \"api-opportunity-documented\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiValuePropositionCanvas\",\r\n \"customerJourneyCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"hides-raw-backend-data\",\r\n \"label\": \"API hides raw backend data and is designed for shared use\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"interactionCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/domainCanvas.empty.json\",\r\n \"specs/canvases/api-design/interactionCanvas.empty.json\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"design-consistent\",\r\n \"label\": \"API design is consistent with other APIs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-02\",\r\n \"REST-CX-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-design/restCanvas.empty.json\",\r\n \"docs/api/design/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"descriptive-english-naming\",\r\n \"label\": \"Data and attribute naming uses descriptive English\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"fieldNamesDescriptive\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"mandatory-fields-specified\",\r\n \"label\": \"Mandatory fields are specified\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"requiredFieldsPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"dates-use-iso\",\r\n \"label\": \"Dates use ISO format with timezone\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"dateFormatTimezone\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"general-data-uses-standard-values\",\r\n \"label\": \"General data uses standard values\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"standardizedEnumsOrPatterns\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"field-names-avoid-acronyms\",\r\n \"label\": \"Field names avoid acronyms and use full words\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"avoidAcronyms\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"create-returns-identifiers\",\r\n \"label\": \"Creating new resources returns identifiers\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is read-only and does not create resources.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"paths-max-two-resources\",\r\n \"label\": \"Endpoint paths contain max two resources or sub-resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"pathDepthMax\",\r\n \"maxDepth\": 2\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PATH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"examples-present\",\r\n \"label\": \"Endpoints and attributes include examples\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-for-create-update\",\r\n \"label\": \"POST is used for create or update\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose create or update operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-for-remove\",\r\n \"label\": \"DELETE is used to remove resources\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose delete operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-no-request-body\",\r\n \"label\": \"GET has no request body and returns content\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"getNoRequestBody\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-empty-returns-204\",\r\n \"label\": \"GET returns 204 if response body is empty\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current contract returns content for all GET operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-200\",\r\n \"label\": \"POST returns 200 OK when updating\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST updates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-201\",\r\n \"label\": \"POST returns 201 Created with ID on create\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST creates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-returns-204\",\r\n \"label\": \"DELETE returns 204 on success\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose DELETE operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"400-errors-specific\",\r\n \"label\": \"400 errors provide specific error information\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"errorResponsesSpecific\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-400-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"api-audit-checklist\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"401-unauthorized\",\r\n \"label\": \"401 Unauthorized for wrong credentials\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current public storefront contract is intentionally unauthenticated.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-401-01\",\r\n \"REST-SEC-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"403-forbidden\",\r\n \"label\": \"403 Forbidden for unauthorized operations\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current profile is public read-only and exposes no unauthorized operations.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-403-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-contains-schemas\",\r\n \"label\": \"Spec contains request and response schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"schemasPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"restCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"pseudo-identifiers\",\r\n \"label\": \"UUIDs or pseudo-identifiers instead of DB IDs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"opaqueIdentifiers\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-07\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"no-sensitive-data-in-urls\",\r\n \"label\": \"No sensitive data in URLs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"noSensitiveDataInPaths\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-06\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"http-methods-match-resources\",\r\n \"label\": \"HTTP methods only for intended resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"methodResourceConsistency\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\",\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4,\r\n \"items\": [\r\n {\r\n \"id\": \"design-items-audited\",\r\n \"label\": \"All prototype and design items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"design\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"design-reflects-business-value\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/production-readiness-review.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-validated-on-change\",\r\n \"label\": \"Spec validated on every change\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"validationWorkflowPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\",\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"schema-and-examples-pass\",\r\n \"label\": \"Schema and examples pass validation\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPassValidation\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-contract-tested\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\",\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"api-audit-checklist\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"uses-https\",\r\n \"label\": \"Uses HTTPS or encrypted protocols\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"auth-protection\",\r\n \"label\": \"Endpoints protected by authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"token-auth\",\r\n \"label\": \"Token-based authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"csrf-protection\",\r\n \"label\": \"Protected against CSRF\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-08\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-development-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"inputs-auto-validated\",\r\n \"label\": \"Inputs auto-validated by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"contract-first-design\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\",\r\n \"test\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"outputs-auto-escaped\",\r\n \"label\": \"Outputs auto-escaped by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"JSON APIs do not typically require output escaping in the same way as HTML rendering.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"encryption-in-transit\",\r\n \"label\": \"Encryption for data in transit and storage\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"infra-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"message-integrity\",\r\n \"label\": \"Message integrity implemented\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"monitoring\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5,\r\n \"items\": [\r\n {\r\n \"id\": \"published-via-api-management\",\r\n \"label\": \"Published via API management\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"ci-cd\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"visible-in-dev-portal\",\r\n \"label\": \"Visible in developer portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-community-engagement-strategies\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"docs-auto-generated\",\r\n \"label\": \"Docs auto-generated from spec and schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\",\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"documentation\",\r\n \"ci-cd\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/publishing/README.md\",\r\n \"docs/api/audit/design-audit.read-only.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-auto-updated\",\r\n \"label\": \"Spec auto-updated to gateway and dev portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"contract-first-design\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"gateway-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"official-domain\",\r\n \"label\": \"Published under official organization domain\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6,\r\n \"items\": []\r\n }\r\n ],\r\n \"guidelines\": [\r\n {\r\n \"id\": \"REST-CONTRACT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST implement endpoints, parameters, request bodies, response bodies, and error responses as defined in the validated OpenAPI contract.\",\r\n \"relatedAuditItems\": [\r\n \"spec-contains-schemas\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CONTRACT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST keep the implementation, published OpenAPI description, gateway configuration, and developer portal documentation aligned on every change.\",\r\n \"relatedAuditItems\": [\r\n \"docs-auto-generated\",\r\n \"spec-auto-updated\",\r\n \"spec-validated-on-change\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VALIDATION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate path parameters, query parameters, headers, and JSON request bodies against the OpenAPI schema before business processing.\",\r\n \"relatedAuditItems\": [\r\n \"mandatory-fields-specified\",\r\n \"400-errors-specific\",\r\n \"inputs-auto-validated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST expose business-oriented resources and attributes rather than raw backend tables, internal service payloads, or system-specific field names.\",\r\n \"relatedAuditItems\": [\r\n \"based-on-clear-business-needs\",\r\n \"hides-raw-backend-data\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST preserve validated meanings of entities, attributes, statuses, and source-of-truth rules across all endpoints and operations.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\",\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use descriptive English names for resources and attributes.\",\r\n \"relatedAuditItems\": [\r\n \"descriptive-english-naming\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST avoid unexplained acronyms in public field and resource names.\",\r\n \"relatedAuditItems\": [\r\n \"field-names-avoid-acronyms\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use ISO date-time values with timezone information where dates are exposed.\",\r\n \"relatedAuditItems\": [\r\n \"dates-use-iso\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API SHOULD use standard codes, controlled vocabularies, and standardized value sets where applicable.\",\r\n \"relatedAuditItems\": [\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST describe the business value and feature intent of each endpoint or capability.\",\r\n \"relatedAuditItems\": [\r\n \"endpoint-descriptions-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST include examples for endpoints, request bodies, response bodies, and key attributes.\",\r\n \"relatedAuditItems\": [\r\n \"examples-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API SHOULD use consistent pagination, filtering, sorting, and response conventions across resources.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-GET-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use GET for safe read-only operations and MUST NOT define a request body for GET operations.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-POST-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use POST for resource creation and other non-idempotent operations.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-PUT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use PUT only for full resource replacement.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-DELETE-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use DELETE to remove resources.\",\r\n \"relatedAuditItems\": [\r\n \"delete-for-remove\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PATH-01\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"resource-modeling\",\r\n \"requirement\": \"The REST API SHOULD keep endpoint paths shallow and avoid more than two resource or sub-resource levels unless explicitly justified.\",\r\n \"relatedAuditItems\": [\r\n \"paths-max-two-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-200-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 200 OK for successful reads and updates that include a response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"post-returns-200\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-201-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 201 Created and the created resource identifier when a new resource is created.\",\r\n \"relatedAuditItems\": [\r\n \"create-returns-identifiers\",\r\n \"post-returns-201\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 204 No Content for successful delete operations that do not return a body.\",\r\n \"relatedAuditItems\": [\r\n \"delete-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API SHOULD return 204 No Content for successful operations that intentionally return no response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-empty-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-400-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST define 400 Bad Request responses with specific and actionable validation error information.\",\r\n \"relatedAuditItems\": [\r\n \"400-errors-specific\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-401-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 401 Unauthorized for missing or invalid credentials.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-403-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 403 Forbidden for authenticated clients lacking sufficient permission.\",\r\n \"relatedAuditItems\": [\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VERSION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"versioning\",\r\n \"requirement\": \"The REST API MUST define a versioning strategy before production release, and the strategy MUST be supportable by the API gateway.\",\r\n \"relatedAuditItems\": [\r\n \"versioning-decided\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST require authentication for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use token-based authentication or another approved modern authentication mechanism for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"token-auth\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-03\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST enforce object-level and function-level authorization on every protected operation.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\",\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST mitigate OWASP API risks including broken object level authorization, broken function level authorization, injection, and unrestricted resource consumption.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"rate-limits-enforced\",\r\n \"no-sensitive-data-in-urls\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-05\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use HTTPS or another approved encrypted protocol for all traffic.\",\r\n \"relatedAuditItems\": [\r\n \"uses-https\",\r\n \"encryption-in-transit\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-06\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST NOT expose sensitive information in URLs, query strings, logs, or unnecessary response fields.\",\r\n \"relatedAuditItems\": [\r\n \"no-sensitive-data-in-urls\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-07\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API SHOULD use UUIDs or other non-sequential public identifiers where direct database identifiers would increase exposure risk.\",\r\n \"relatedAuditItems\": [\r\n \"pseudo-identifiers\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-08\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST implement CSRF protection where relevant to the authentication model and client interaction pattern.\",\r\n \"relatedAuditItems\": [\r\n \"csrf-protection\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST define and enforce rate limits, throttling, or quotas according to capacity expectations.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST implement resilience controls such as timeouts, fallback behavior, and degradation handling according to business impact.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-OBS-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"observability\",\r\n \"requirement\": \"The REST API MUST implement logs, metrics, and monitoring needed to observe validation failures, auth failures, traffic, latency, and dependency health.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published through an API management platform.\",\r\n \"relatedAuditItems\": [\r\n \"published-via-api-management\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be accessible only through approved API gateway paths and managed entry points.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API SHOULD be visible in a developer portal with documentation generated from the contract.\",\r\n \"relatedAuditItems\": [\r\n \"visible-in-dev-portal\",\r\n \"docs-auto-generated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published under an approved organizational domain.\",\r\n \"relatedAuditItems\": [\r\n \"official-domain\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate the specification, schema, and examples on every change.\",\r\n \"relatedAuditItems\": [\r\n \"spec-validated-on-change\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST pass concept, design, security, and production-readiness checks before release.\",\r\n \"relatedAuditItems\": [\r\n \"concept-items-audited\",\r\n \"design-items-audited\"\r\n ]\r\n }\r\n ]\r\n}\r\n", "draft": false }, { "id": "api-compliance-best-practices", "slug": "resources/api-compliance-best-practices", "title": "Boas práticas de conformidade da API", "description": "Garantir que as APIs cumprem conformidade legal, regulamentar e interna através de documentação, controlos e validações automatizadas.", "category": "guideline", "icon": "edit-document-outline", "order": 104, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de conformidade da API", "Abordagem normalizada utilizando as Melhores Práticas de Conformidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Documentar as medidas de conformidade e garantir que são comunicadas às partes interessadas e aos utilizadores.", "Implementar medidas para garantir que as APIs cumprem estes requisitos, incluindo encriptação de dados, controlos de acesso e pistas de auditoria.", "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false } ], "promptIds": [ "api-engineer:facilitate-station", "api-engineer:use-resources", "api-engineer:next-actions" ] }, { "id": "domain-specialist", "stakeholderId": "domain-specialist", "title": "Especialista de domínio", "summary": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "stakeholder": { "id": "domain-specialist", "sourceKey": "domain-specialist", "sourceStakeholderId": "domain-specialist", "title": "Especialista de domínio", "description": "Traz conhecimento profundo do domínio de negócio, conceitos, regras e restrições que a capacidade ou interface deve refletir.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." }, { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." }, { "id": "api-consumer-experience", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento." }, { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." }, { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." } ], "canvases": [ { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "capabilityBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da Capacidade" }, { "id": "consumerExperienceRequirementsCanvas", "title": "Canvas de Requisitos da Experiência do Utilizador" }, { "id": "interactionCanvas", "title": "Canvas de Interação" }, { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" }, { "id": "apiValuePropositionCanvas", "title": "Canvas da Proposta de Valor da API" }, { "id": "apiBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da API" }, { "id": "restCanvas", "title": "Canvas REST" }, { "id": "eventCanvas", "title": "Canvas de Eventos" }, { "id": "graphqlCanvas", "title": "Canvas GraphQL" } ], "decisions": [ "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais." ], "outputs": [ "Uma proposta de valor e um público-alvo da API simples", "Linguagem partilhada entre o produto, a conceção e a tecnologia", "Um argumento sólido ou um caso para financiamento/aprovação", "design-artifact", "documentation", "research", "roadmap", "Identifique e dê prioridade aos seus consumidores de API" ], "recommendedResources": [ { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityBusinessModelCanvas", "slug": "resources/capability-business-model-canvas", "title": "Canvas do Modelo de Negócio da Capacidade", "description": "Um canvas de modelo de negócio para capacidades de integração reutilizáveis, cobrindo valor, utilizadores, propriedade, envolvimento, custos e benefícios sem assumir disponibilização por API.", "category": "canvas", "icon": "dashboard-outline", "order": 3.1, "outcomes": [ "Modelo operacional viável para a capacidade reutilizável", "Propriedade, utilizadores, canais, parceiros e necessidades de suporte clarificados", "Custos e benefícios visíveis antes do compromisso com a arquitetura" ], "steps": [ "Resuma a proposta de valor da capacidade.", "Identifique segmentos de utilizadores e canais de envolvimento.", "Defina atividades, recursos e parceiros-chave.", "Capte custos e benefícios.", "Clarifique propriedade, financiamento, suporte e expectativas de ciclo de vida.", "Valide o modelo com utilizadores, produtores e partes interessadas de governação." ], "canvasId": "capabilityBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "contract-first-design", "slug": "resources/contract-first-design", "title": "Primeira conceção do contrato", "description": "Uma diretriz que defende abordagens API-first utilizando contratos formais (por exemplo, OpenAPI) para alinhar as partes interessadas antes do desenvolvimento.", "category": "guideline", "icon": "edit-document-outline", "order": 146, "outcomes": [ "Melhor compreensão dos princípios de conceção da primeira fase do contrato", "Abordagem normalizada utilizando a conceção orientada por contrato", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar." ], "canvasId": null, "sourcePath": "src/snippets/api-contract-example.yaml", "sourceUrl": null, "contentMarkdown": "openapi: 3.0.3\r\ninfo:\r\n title: Sample Catalog API\r\n version: 1.0.0\r\n description: |\r\n Starter example for a read-only APIOps Cycles API.\r\n This example keeps the contract audit-friendly and easy to extend.\r\nservers:\r\n - url: /v1\r\n description: Versioned API base path\r\ntags:\r\n - name: catalog\r\n description: Browse and search catalog items\r\npaths:\r\n /items:\r\n get:\r\n tags: [catalog]\r\n summary: List catalog items\r\n description: Returns a paginated list of public catalog items.\r\n operationId: listItems\r\n parameters:\r\n - $ref: \"#/components/parameters/searchTerm\"\r\n - $ref: \"#/components/parameters/categoryId\"\r\n - $ref: \"#/components/parameters/page\"\r\n - $ref: \"#/components/parameters/pageSize\"\r\n responses:\r\n \"200\":\r\n description: Item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n examples:\r\n default:\r\n value:\r\n data:\r\n - itemId: item-123\r\n slug: blue-widget\r\n name: Blue Widget\r\n status: published\r\n page:\r\n number: 1\r\n size: 20\r\n totalItems: 1\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"429\":\r\n $ref: \"#/components/responses/TooManyRequests\"\r\n /items/{itemId}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by id\r\n description: Returns a single public catalog item by opaque identifier.\r\n operationId: getItemById\r\n parameters:\r\n - $ref: \"#/components/parameters/itemId\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /items/by-slug/{slug}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by slug\r\n description: Returns a single item by public slug.\r\n operationId: getItemBySlug\r\n parameters:\r\n - $ref: \"#/components/parameters/slug\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /categories/{categoryId}/items:\r\n get:\r\n tags: [catalog]\r\n summary: List items in category\r\n description: Returns public items in a category.\r\n operationId: listItemsByCategory\r\n parameters:\r\n - $ref: \"#/components/parameters/categoryId\"\r\n responses:\r\n \"200\":\r\n description: Category item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\ncomponents:\r\n parameters:\r\n itemId:\r\n name: itemId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: item-123\r\n slug:\r\n name: slug\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9]+(?:-[a-z0-9]+)*$\"\r\n example: blue-widget\r\n categoryId:\r\n name: categoryId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: home-goods\r\n searchTerm:\r\n name: searchTerm\r\n in: query\r\n required: false\r\n schema:\r\n type: string\r\n minLength: 1\r\n example: widget\r\n page:\r\n name: page\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n default: 1\r\n pageSize:\r\n name: pageSize\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n maximum: 100\r\n default: 20\r\n responses:\r\n BadRequest:\r\n description: Validation failed\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n examples:\r\n default:\r\n value:\r\n code: BAD_REQUEST\r\n message: Invalid request\r\n NotFound:\r\n description: Resource not found\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n TooManyRequests:\r\n description: Rate limit exceeded\r\n headers:\r\n Retry-After:\r\n schema:\r\n type: integer\r\n description: Seconds until the next allowed request.\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n schemas:\r\n ItemListResponse:\r\n type: object\r\n required: [data, page]\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/ItemSummary\"\r\n page:\r\n $ref: \"#/components/schemas/Page\"\r\n ItemSummary:\r\n type: object\r\n required: [itemId, slug, name, status]\r\n properties:\r\n itemId:\r\n type: string\r\n slug:\r\n type: string\r\n name:\r\n type: string\r\n status:\r\n type: string\r\n enum: [published, hidden]\r\n ItemDetail:\r\n allOf:\r\n - $ref: \"#/components/schemas/ItemSummary\"\r\n - type: object\r\n properties:\r\n description:\r\n type: string\r\n categories:\r\n type: array\r\n items:\r\n type: string\r\n variants:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/Variant\"\r\n Variant:\r\n type: object\r\n required: [variantId, sku, price, inventory]\r\n properties:\r\n variantId:\r\n type: string\r\n sku:\r\n type: string\r\n price:\r\n $ref: \"#/components/schemas/Price\"\r\n inventory:\r\n $ref: \"#/components/schemas/Inventory\"\r\n Price:\r\n type: object\r\n required: [amount, currency]\r\n properties:\r\n amount:\r\n type: number\r\n format: decimal\r\n currency:\r\n type: string\r\n example: EUR\r\n Inventory:\r\n type: object\r\n required: [available]\r\n properties:\r\n available:\r\n type: integer\r\n minimum: 0\r\n reserved:\r\n type: integer\r\n minimum: 0\r\n source:\r\n type: string\r\n Page:\r\n type: object\r\n required: [number, size, totalItems]\r\n properties:\r\n number:\r\n type: integer\r\n size:\r\n type: integer\r\n totalItems:\r\n type: integer\r\n ErrorResponse:\r\n type: object\r\n required: [code, message]\r\n properties:\r\n code:\r\n type: string\r\n message:\r\n type: string\r\n", "draft": true }, { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false } ], "promptIds": [ "domain-specialist:facilitate-station", "domain-specialist:use-resources", "domain-specialist:next-actions" ] }, { "id": "compliance-specialist", "stakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "summary": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "stakeholder": { "id": "compliance-specialist", "sourceKey": "compliance-specialist", "sourceStakeholderId": "compliance-specialist", "title": "Especialista em conformidade e jurídico", "description": "Esclarece requisitos legais, de privacidade, regulamentares e contratuais que afetam a capacidade, API, interface ou automatização.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." }, { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." }, { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." }, { "id": "api-delivery", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia." }, { "id": "api-audit", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." }, { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." }, { "id": "api-publishing", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos." }, { "id": "api-consumer-experience", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento." } ], "canvases": [ { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "capabilityBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da Capacidade" }, { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" }, { "id": "interactionCanvas", "title": "Canvas de Interação" }, { "id": "consumerExperienceRequirementsCanvas", "title": "Canvas de Requisitos da Experiência do Utilizador" }, { "id": "apiValuePropositionCanvas", "title": "Canvas da Proposta de Valor da API" }, { "id": "apiBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da API" }, { "id": "restCanvas", "title": "Canvas REST" }, { "id": "eventCanvas", "title": "Canvas de Eventos" }, { "id": "graphqlCanvas", "title": "Canvas GraphQL" } ], "decisions": [ "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais." ], "outputs": [ "Uma proposta de valor e um público-alvo da API simples", "Linguagem partilhada entre o produto, a conceção e a tecnologia", "Um argumento sólido ou um caso para financiamento/aprovação", "design-artifact", "documentation", "research", "roadmap", "Corte APIs redundantes e reduza os custos da plataforma de nuvem" ], "recommendedResources": [ { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityBusinessModelCanvas", "slug": "resources/capability-business-model-canvas", "title": "Canvas do Modelo de Negócio da Capacidade", "description": "Um canvas de modelo de negócio para capacidades de integração reutilizáveis, cobrindo valor, utilizadores, propriedade, envolvimento, custos e benefícios sem assumir disponibilização por API.", "category": "canvas", "icon": "dashboard-outline", "order": 3.1, "outcomes": [ "Modelo operacional viável para a capacidade reutilizável", "Propriedade, utilizadores, canais, parceiros e necessidades de suporte clarificados", "Custos e benefícios visíveis antes do compromisso com a arquitetura" ], "steps": [ "Resuma a proposta de valor da capacidade.", "Identifique segmentos de utilizadores e canais de envolvimento.", "Defina atividades, recursos e parceiros-chave.", "Capte custos e benefícios.", "Clarifique propriedade, financiamento, suporte e expectativas de ciclo de vida.", "Valide o modelo com utilizadores, produtores e partes interessadas de governação." ], "canvasId": "capabilityBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-development-best-practices", "slug": "resources/api-development-best-practices", "title": "Boas práticas de desenvolvimento de API", "description": "Orientações de implementação para transformar um contrato de interface da API validado numa base de código de API consistente e sustentável, utilizando bibliotecas padrão, padrões reutilizáveis e fluxos de trabalho de desenvolvimento alinhados.", "category": "guideline", "icon": "edit-document-outline", "order": 112, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de desenvolvimento de API", "Abordagem normalizada utilizando as boas práticas de desenvolvimento de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplique essas práticas ao contrato de interface da API validado e ao plano de implementação antes do início da codificação.", "Utilize frameworks, bibliotecas e padrões de codificação estabelecidos para implementar o contrato de forma consistente e sustentável." ], "canvasId": null, "sourcePath": "src/snippets/pt/api-design-principles-guidance.md", "sourceUrl": null, "contentMarkdown": "## Como iniciar o trabalho de entrega da API com base nas fases anteriores (“etapas”)\r\nUtilize estas orientações no início da `API Delivery` (entrega da API), após a revisão e aceitação do contrato da API (por exemplo, OpenAPI) e dos principais resultados das etapas anteriores.\r\nO objetivo não é desenvolver a implementação de forma isolada. O objetivo é transformar os resultados acordados nas etapas anteriores em uma estrutura de código concreta, regras de validação, comportamento em tempo de execução e decisões relativas à entrega do produto API.\r\n\r\n---\r\n\r\n### 1. Comece a partir do contrato validado\r\n- Trate o contrato de API validado como o principal ponto de referência para as decisões de implementação.\r\n- Mantenha o contrato e a implementação alinhados ao longo de toda a entrega do produto API.\r\n- Use o contrato para orientar a validação de solicitações, o mapeamento de respostas, a documentação e os testes.\r\n\r\n---\r\n\r\n### 2. Use os resultados do domínio para preservar o significado comercial\r\n- Use os resultados do `Domain Canvas` para orientar a nomenclatura, como a implementação é dividida em responsabilidades comerciais claras e como diferentes sistemas de back-end são conectados sem expor suas diferenças.\r\n- Preserve os significados validados de entidades, atributos, status e regras de fonte de verdade.\r\n- Evite vazar modelos específicos do back-end ou inconsistências para a API pública.\r\n\r\n---\r\n\r\n### 3. Use os resultados da jornada para preservar fluxos críticos\r\n- Use os resultados do `Customer Journey Canvas` para identificar quais fluxos de usuários são mais importantes para serem atendidos primeiro.\r\n- Use os resultados da `API Consumer Experience` para manter a API compreensível, previsível e fácil de integrar.\r\n- Deixe que as prioridades de jornada acordadas decidam quais caminhos de implementação precisam da maior confiabilidade, menor latência, erros mais claros e maior foco operacional.\r\n\r\n---\r\n\r\n### 4. Use os resultados da Proposta de Valor para preservar o valor para o consumidor\r\n- Use os resultados do `API Value Proposition Canvas` para manter a implementação focada nas dores, ganhos e recursos da API acordados.\r\n- Preserve os significados dos campos, o comportamento e as promessas que tornaram a API valiosa nas etapas anteriores.\r\n- Garanta que o tratamento de erros, a atualização e a nomenclatura apoiem tanto a experiência do desenvolvedor pretendida quanto o caso de uso de negócios.\r\n\r\n---\r\n\r\n### 5. Use os resultados da arquitetura para moldar as decisões de tempo de execução\r\n- Use os resultados do `Business Impact Canvas` para orientar as decisões sobre resiliência, tempo limite, fallback e degradação.\r\n- Use os resultados do `Locations Canvas` para orientar os limites de rede, limites de confiança, caminhos de acesso e restrições de implantação.\r\n- Use os resultados do `Capacity Canvas` para orientar limites de taxa, cache, escalonamento e comportamento em picos de carga.\r\n- Use as orientações do `API Metrics And Analytics` para decidir o que deve ser observado desde a primeira implementação em diante.\r\n\r\n---\r\n\r\n### 6. Use os resultados do projeto de interação e protocolo para moldar a estrutura do código\r\n- Use os resultados do `Interaction Canvas` para evitar implementar estilos de interação não suportados prematuramente.\r\n- Use os resultados do projeto `REST`, `Event` ou `GraphQL` para moldar o comportamento de solicitação, resposta e validação específico do protocolo.\r\n- Reflete o estilo de interação selecionado claramente na estrutura do código, nas responsabilidades e na estratégia de testes.\r\n\r\n---\r\n\r\n### 7. Usa os resultados da auditoria para melhorar a entrega antes que a codificação avance demais\r\n- Usa as conclusões da auditoria para remover ambiguidades antes que a implementação se espalhe pela base de código.\r\n- Corrige regras de solicitação pouco claras, validações ausentes, contratos de erro fracos e lacunas operacionais logo no início.\r\n- Trate a auditoria como um ciclo de melhoria de projeto antes da produção, não apenas como uma etapa de decisão final.\r\n\r\n---\r\n\r\n### 8. Aplique as orientações e, em seguida, resuma\r\n- Aplique estas orientações à API atual e ao plano de implementação.\r\n- Resuma as implicações para a estrutura do código, validação de solicitações, integração de fontes, segurança, monitoramento e alertas, e testes.\r\n- Não crie um artefato de entrega separado, a menos que a equipe ou o usuário precise especificamente de um.\r\n", "draft": true }, { "id": "api-testing-best-practices", "slug": "resources/api-testing-best-practices", "title": "Boas práticas de teste de API", "description": "Diretrizes para a implementação de testes automatizados funcionais, de desempenho e de segurança ao longo do ciclo de vida da API.", "category": "guideline", "icon": "edit-document-outline", "order": 133, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de teste de API", "Abordagem normalizada utilizando as boas práticas de teste de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Integrar testes funcionais e não funcionais no pipeline CI/CD para garantir que as APIs cumprems normas de qualidade.", "Utilizar ferramentas de teste automatizadas para validar a funcionalidade, a segurança e o desempenho da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "apiops-CI-CD-for-apis", "slug": "resources/apiops-CI-CD-for-apis", "title": "APIOps CI/CD para APIs", "description": "Orientação de disponibilização que integra tarefas do ciclo de vida da API - design, teste, governação - em pipelines de integração e entrega contínuas.", "category": "guideline", "icon": "edit-document-outline", "order": 140, "outcomes": [ "Melhor compreensão dos princípios de CI/CD para APIs", "Abordagem normalizada utilizando CI/CD para APIs", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilizar pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "promptIds": [ "compliance-specialist:facilitate-station", "compliance-specialist:use-resources", "compliance-specialist:next-actions" ] }, { "id": "security-specialist", "stakeholderId": "security-specialist", "title": "Especialista em segurança", "summary": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "stakeholder": { "id": "security-specialist", "sourceKey": "security-specialist", "sourceStakeholderId": "security-specialist", "title": "Especialista em segurança", "description": "Garante que os riscos de segurança, controlos e fronteiras de confiança são tratados ao longo de todo o ciclo de vida.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." }, { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." }, { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." }, { "id": "api-delivery", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia." }, { "id": "api-audit", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição." }, { "id": "api-publishing", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." }, { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." } ], "canvases": [ { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "interactionCanvas", "title": "Canvas de Interação" }, { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "capabilityBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da Capacidade" }, { "id": "restCanvas", "title": "Canvas REST" }, { "id": "eventCanvas", "title": "Canvas de Eventos" }, { "id": "graphqlCanvas", "title": "Canvas GraphQL" }, { "id": "apiValuePropositionCanvas", "title": "Canvas da Proposta de Valor da API" }, { "id": "apiBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da API" } ], "decisions": [ "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência." ], "outputs": [ "Corte APIs redundantes e reduza os custos da plataforma de nuvem", "Implementar uma governação consistente snum forte controlo do topo para a base", "Conceção para reutilização interna e escalabilidade externa", "architecture-decision", "documentation", "platform-config", "metrics", "Conceção de API bem documentada e coerente" ], "recommendedResources": [ { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "contract-first-design", "slug": "resources/contract-first-design", "title": "Primeira conceção do contrato", "description": "Uma diretriz que defende abordagens API-first utilizando contratos formais (por exemplo, OpenAPI) para alinhar as partes interessadas antes do desenvolvimento.", "category": "guideline", "icon": "edit-document-outline", "order": 146, "outcomes": [ "Melhor compreensão dos princípios de conceção da primeira fase do contrato", "Abordagem normalizada utilizando a conceção orientada por contrato", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar." ], "canvasId": null, "sourcePath": "src/snippets/api-contract-example.yaml", "sourceUrl": null, "contentMarkdown": "openapi: 3.0.3\r\ninfo:\r\n title: Sample Catalog API\r\n version: 1.0.0\r\n description: |\r\n Starter example for a read-only APIOps Cycles API.\r\n This example keeps the contract audit-friendly and easy to extend.\r\nservers:\r\n - url: /v1\r\n description: Versioned API base path\r\ntags:\r\n - name: catalog\r\n description: Browse and search catalog items\r\npaths:\r\n /items:\r\n get:\r\n tags: [catalog]\r\n summary: List catalog items\r\n description: Returns a paginated list of public catalog items.\r\n operationId: listItems\r\n parameters:\r\n - $ref: \"#/components/parameters/searchTerm\"\r\n - $ref: \"#/components/parameters/categoryId\"\r\n - $ref: \"#/components/parameters/page\"\r\n - $ref: \"#/components/parameters/pageSize\"\r\n responses:\r\n \"200\":\r\n description: Item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n examples:\r\n default:\r\n value:\r\n data:\r\n - itemId: item-123\r\n slug: blue-widget\r\n name: Blue Widget\r\n status: published\r\n page:\r\n number: 1\r\n size: 20\r\n totalItems: 1\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"429\":\r\n $ref: \"#/components/responses/TooManyRequests\"\r\n /items/{itemId}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by id\r\n description: Returns a single public catalog item by opaque identifier.\r\n operationId: getItemById\r\n parameters:\r\n - $ref: \"#/components/parameters/itemId\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /items/by-slug/{slug}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by slug\r\n description: Returns a single item by public slug.\r\n operationId: getItemBySlug\r\n parameters:\r\n - $ref: \"#/components/parameters/slug\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /categories/{categoryId}/items:\r\n get:\r\n tags: [catalog]\r\n summary: List items in category\r\n description: Returns public items in a category.\r\n operationId: listItemsByCategory\r\n parameters:\r\n - $ref: \"#/components/parameters/categoryId\"\r\n responses:\r\n \"200\":\r\n description: Category item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\ncomponents:\r\n parameters:\r\n itemId:\r\n name: itemId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: item-123\r\n slug:\r\n name: slug\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9]+(?:-[a-z0-9]+)*$\"\r\n example: blue-widget\r\n categoryId:\r\n name: categoryId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: home-goods\r\n searchTerm:\r\n name: searchTerm\r\n in: query\r\n required: false\r\n schema:\r\n type: string\r\n minLength: 1\r\n example: widget\r\n page:\r\n name: page\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n default: 1\r\n pageSize:\r\n name: pageSize\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n maximum: 100\r\n default: 20\r\n responses:\r\n BadRequest:\r\n description: Validation failed\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n examples:\r\n default:\r\n value:\r\n code: BAD_REQUEST\r\n message: Invalid request\r\n NotFound:\r\n description: Resource not found\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n TooManyRequests:\r\n description: Rate limit exceeded\r\n headers:\r\n Retry-After:\r\n schema:\r\n type: integer\r\n description: Seconds until the next allowed request.\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n schemas:\r\n ItemListResponse:\r\n type: object\r\n required: [data, page]\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/ItemSummary\"\r\n page:\r\n $ref: \"#/components/schemas/Page\"\r\n ItemSummary:\r\n type: object\r\n required: [itemId, slug, name, status]\r\n properties:\r\n itemId:\r\n type: string\r\n slug:\r\n type: string\r\n name:\r\n type: string\r\n status:\r\n type: string\r\n enum: [published, hidden]\r\n ItemDetail:\r\n allOf:\r\n - $ref: \"#/components/schemas/ItemSummary\"\r\n - type: object\r\n properties:\r\n description:\r\n type: string\r\n categories:\r\n type: array\r\n items:\r\n type: string\r\n variants:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/Variant\"\r\n Variant:\r\n type: object\r\n required: [variantId, sku, price, inventory]\r\n properties:\r\n variantId:\r\n type: string\r\n sku:\r\n type: string\r\n price:\r\n $ref: \"#/components/schemas/Price\"\r\n inventory:\r\n $ref: \"#/components/schemas/Inventory\"\r\n Price:\r\n type: object\r\n required: [amount, currency]\r\n properties:\r\n amount:\r\n type: number\r\n format: decimal\r\n currency:\r\n type: string\r\n example: EUR\r\n Inventory:\r\n type: object\r\n required: [available]\r\n properties:\r\n available:\r\n type: integer\r\n minimum: 0\r\n reserved:\r\n type: integer\r\n minimum: 0\r\n source:\r\n type: string\r\n Page:\r\n type: object\r\n required: [number, size, totalItems]\r\n properties:\r\n number:\r\n type: integer\r\n size:\r\n type: integer\r\n totalItems:\r\n type: integer\r\n ErrorResponse:\r\n type: object\r\n required: [code, message]\r\n properties:\r\n code:\r\n type: string\r\n message:\r\n type: string\r\n", "draft": true }, { "id": "api-development-best-practices", "slug": "resources/api-development-best-practices", "title": "Boas práticas de desenvolvimento de API", "description": "Orientações de implementação para transformar um contrato de interface da API validado numa base de código de API consistente e sustentável, utilizando bibliotecas padrão, padrões reutilizáveis e fluxos de trabalho de desenvolvimento alinhados.", "category": "guideline", "icon": "edit-document-outline", "order": 112, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de desenvolvimento de API", "Abordagem normalizada utilizando as boas práticas de desenvolvimento de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplique essas práticas ao contrato de interface da API validado e ao plano de implementação antes do início da codificação.", "Utilize frameworks, bibliotecas e padrões de codificação estabelecidos para implementar o contrato de forma consistente e sustentável." ], "canvasId": null, "sourcePath": "src/snippets/pt/api-design-principles-guidance.md", "sourceUrl": null, "contentMarkdown": "## Como iniciar o trabalho de entrega da API com base nas fases anteriores (“etapas”)\r\nUtilize estas orientações no início da `API Delivery` (entrega da API), após a revisão e aceitação do contrato da API (por exemplo, OpenAPI) e dos principais resultados das etapas anteriores.\r\nO objetivo não é desenvolver a implementação de forma isolada. O objetivo é transformar os resultados acordados nas etapas anteriores em uma estrutura de código concreta, regras de validação, comportamento em tempo de execução e decisões relativas à entrega do produto API.\r\n\r\n---\r\n\r\n### 1. Comece a partir do contrato validado\r\n- Trate o contrato de API validado como o principal ponto de referência para as decisões de implementação.\r\n- Mantenha o contrato e a implementação alinhados ao longo de toda a entrega do produto API.\r\n- Use o contrato para orientar a validação de solicitações, o mapeamento de respostas, a documentação e os testes.\r\n\r\n---\r\n\r\n### 2. Use os resultados do domínio para preservar o significado comercial\r\n- Use os resultados do `Domain Canvas` para orientar a nomenclatura, como a implementação é dividida em responsabilidades comerciais claras e como diferentes sistemas de back-end são conectados sem expor suas diferenças.\r\n- Preserve os significados validados de entidades, atributos, status e regras de fonte de verdade.\r\n- Evite vazar modelos específicos do back-end ou inconsistências para a API pública.\r\n\r\n---\r\n\r\n### 3. Use os resultados da jornada para preservar fluxos críticos\r\n- Use os resultados do `Customer Journey Canvas` para identificar quais fluxos de usuários são mais importantes para serem atendidos primeiro.\r\n- Use os resultados da `API Consumer Experience` para manter a API compreensível, previsível e fácil de integrar.\r\n- Deixe que as prioridades de jornada acordadas decidam quais caminhos de implementação precisam da maior confiabilidade, menor latência, erros mais claros e maior foco operacional.\r\n\r\n---\r\n\r\n### 4. Use os resultados da Proposta de Valor para preservar o valor para o consumidor\r\n- Use os resultados do `API Value Proposition Canvas` para manter a implementação focada nas dores, ganhos e recursos da API acordados.\r\n- Preserve os significados dos campos, o comportamento e as promessas que tornaram a API valiosa nas etapas anteriores.\r\n- Garanta que o tratamento de erros, a atualização e a nomenclatura apoiem tanto a experiência do desenvolvedor pretendida quanto o caso de uso de negócios.\r\n\r\n---\r\n\r\n### 5. Use os resultados da arquitetura para moldar as decisões de tempo de execução\r\n- Use os resultados do `Business Impact Canvas` para orientar as decisões sobre resiliência, tempo limite, fallback e degradação.\r\n- Use os resultados do `Locations Canvas` para orientar os limites de rede, limites de confiança, caminhos de acesso e restrições de implantação.\r\n- Use os resultados do `Capacity Canvas` para orientar limites de taxa, cache, escalonamento e comportamento em picos de carga.\r\n- Use as orientações do `API Metrics And Analytics` para decidir o que deve ser observado desde a primeira implementação em diante.\r\n\r\n---\r\n\r\n### 6. Use os resultados do projeto de interação e protocolo para moldar a estrutura do código\r\n- Use os resultados do `Interaction Canvas` para evitar implementar estilos de interação não suportados prematuramente.\r\n- Use os resultados do projeto `REST`, `Event` ou `GraphQL` para moldar o comportamento de solicitação, resposta e validação específico do protocolo.\r\n- Reflete o estilo de interação selecionado claramente na estrutura do código, nas responsabilidades e na estratégia de testes.\r\n\r\n---\r\n\r\n### 7. Usa os resultados da auditoria para melhorar a entrega antes que a codificação avance demais\r\n- Usa as conclusões da auditoria para remover ambiguidades antes que a implementação se espalhe pela base de código.\r\n- Corrige regras de solicitação pouco claras, validações ausentes, contratos de erro fracos e lacunas operacionais logo no início.\r\n- Trate a auditoria como um ciclo de melhoria de projeto antes da produção, não apenas como uma etapa de decisão final.\r\n\r\n---\r\n\r\n### 8. Aplique as orientações e, em seguida, resuma\r\n- Aplique estas orientações à API atual e ao plano de implementação.\r\n- Resuma as implicações para a estrutura do código, validação de solicitações, integração de fontes, segurança, monitoramento e alertas, e testes.\r\n- Não crie um artefato de entrega separado, a menos que a equipe ou o usuário precise especificamente de um.\r\n", "draft": true }, { "id": "api-testing-best-practices", "slug": "resources/api-testing-best-practices", "title": "Boas práticas de teste de API", "description": "Diretrizes para a implementação de testes automatizados funcionais, de desempenho e de segurança ao longo do ciclo de vida da API.", "category": "guideline", "icon": "edit-document-outline", "order": 133, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de teste de API", "Abordagem normalizada utilizando as boas práticas de teste de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Integrar testes funcionais e não funcionais no pipeline CI/CD para garantir que as APIs cumprems normas de qualidade.", "Utilizar ferramentas de teste automatizadas para validar a funcionalidade, a segurança e o desempenho da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "apiops-CI-CD-for-apis", "slug": "resources/apiops-CI-CD-for-apis", "title": "APIOps CI/CD para APIs", "description": "Orientação de disponibilização que integra tarefas do ciclo de vida da API - design, teste, governação - em pipelines de integração e entrega contínuas.", "category": "guideline", "icon": "edit-document-outline", "order": 140, "outcomes": [ "Melhor compreensão dos princípios de CI/CD para APIs", "Abordagem normalizada utilizando CI/CD para APIs", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilizar pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-audit-checklist", "slug": "resources/api-audit-checklist", "title": "Lista de verificação de auditoria da API", "description": "Uma lista de verificação baseada no ciclo de vida para verificar a prontidão da API em design, entrega, publicação e conformidade utilizando critérios de auditoria e evidências definidos.", "category": "checklist", "icon": "check-box-outline", "order": 13, "outcomes": [ "Melhor compreensão dos princípios da lista de controlo de auditoria da API", "Abordagem normalizada utilizando a lista de verificação de auditoria da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilize a lista de verificação de auditoria da API para garantir que a conceção da API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Realize auditorias para avaliar a cobertura do ciclo de vida e verificar se a API satisfaz os padrões de negócio, conceção e operacionais.", "Certifique-se de que a documentação, os modelos de segurança, a configuração do gateway e os requisitos legais estejam claramente definidos, validados e comprovados por evidências." ], "canvasId": null, "sourcePath": "src/snippets/api-audit-checklist.json", "sourceUrl": null, "contentMarkdown": "{\r\n \"profiles\": {\r\n \"read-only\": {\r\n \"description\": \"API profile that is read-only and does not allow create, update, or delete operations.\"\r\n },\r\n \"full-crud\": {\r\n \"description\": \"General API profile that allows create, update, and delete operations.\"\r\n }\r\n },\r\n \"lifecycleStages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6\r\n }\r\n ],\r\n \"stages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1,\r\n \"items\": [\r\n {\r\n \"id\": \"based-on-clear-business-needs\",\r\n \"label\": \"API is based on clear business needs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiBusinessModelCanvas\",\r\n \"apiValuePropositionCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"design-artifact\",\r\n \"documentation\",\r\n \"research\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\",\r\n \"specs/canvases/api-product-strategy/apiBusinessModelCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"concept-items-audited\",\r\n \"label\": \"All concept checklist items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"strategy\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\",\r\n \"api-opportunity-documented\",\r\n \"api-reusability\",\r\n \"value-prop-validated\",\r\n \"consumer-segments-identified\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/concept-review-report.json\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2,\r\n \"items\": [\r\n {\r\n \"id\": \"versioning-decided\",\r\n \"label\": \"Versioning strategy decided and supported by gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VERSION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-versioning-best-practices\",\r\n \"apiops-CI-CD-for-apis\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"ci-cd\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"only-via-gateway\",\r\n \"label\": \"Only accessible via API gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-02\",\r\n \"REST-CAPACITY-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"businessImpactCanvas\",\r\n \"locationsCanvas\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"infra-config\",\r\n \"security-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"rate-limits-enforced\",\r\n \"label\": \"Rate limits are enforced\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CAPACITY-01\",\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"capacityCanvas\",\r\n \"api-security-best-practices\",\r\n \"scalable-infrastructure-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"runtime\",\r\n \"monitoring\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-platform-architecture/capacityCanvas.empty.json\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3,\r\n \"items\": [\r\n {\r\n \"id\": \"endpoint-descriptions-present\",\r\n \"label\": \"Endpoints have business value and feature descriptions\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"operationDescriptions\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\",\r\n \"api-opportunity-documented\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiValuePropositionCanvas\",\r\n \"customerJourneyCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"hides-raw-backend-data\",\r\n \"label\": \"API hides raw backend data and is designed for shared use\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"interactionCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/domainCanvas.empty.json\",\r\n \"specs/canvases/api-design/interactionCanvas.empty.json\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"design-consistent\",\r\n \"label\": \"API design is consistent with other APIs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-02\",\r\n \"REST-CX-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-design/restCanvas.empty.json\",\r\n \"docs/api/design/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"descriptive-english-naming\",\r\n \"label\": \"Data and attribute naming uses descriptive English\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"fieldNamesDescriptive\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"mandatory-fields-specified\",\r\n \"label\": \"Mandatory fields are specified\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"requiredFieldsPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"dates-use-iso\",\r\n \"label\": \"Dates use ISO format with timezone\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"dateFormatTimezone\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"general-data-uses-standard-values\",\r\n \"label\": \"General data uses standard values\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"standardizedEnumsOrPatterns\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"field-names-avoid-acronyms\",\r\n \"label\": \"Field names avoid acronyms and use full words\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"avoidAcronyms\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"create-returns-identifiers\",\r\n \"label\": \"Creating new resources returns identifiers\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is read-only and does not create resources.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"paths-max-two-resources\",\r\n \"label\": \"Endpoint paths contain max two resources or sub-resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"pathDepthMax\",\r\n \"maxDepth\": 2\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PATH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"examples-present\",\r\n \"label\": \"Endpoints and attributes include examples\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-for-create-update\",\r\n \"label\": \"POST is used for create or update\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose create or update operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-for-remove\",\r\n \"label\": \"DELETE is used to remove resources\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose delete operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-no-request-body\",\r\n \"label\": \"GET has no request body and returns content\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"getNoRequestBody\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-empty-returns-204\",\r\n \"label\": \"GET returns 204 if response body is empty\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current contract returns content for all GET operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-200\",\r\n \"label\": \"POST returns 200 OK when updating\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST updates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-201\",\r\n \"label\": \"POST returns 201 Created with ID on create\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST creates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-returns-204\",\r\n \"label\": \"DELETE returns 204 on success\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose DELETE operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"400-errors-specific\",\r\n \"label\": \"400 errors provide specific error information\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"errorResponsesSpecific\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-400-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"api-audit-checklist\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"401-unauthorized\",\r\n \"label\": \"401 Unauthorized for wrong credentials\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current public storefront contract is intentionally unauthenticated.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-401-01\",\r\n \"REST-SEC-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"403-forbidden\",\r\n \"label\": \"403 Forbidden for unauthorized operations\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current profile is public read-only and exposes no unauthorized operations.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-403-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-contains-schemas\",\r\n \"label\": \"Spec contains request and response schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"schemasPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"restCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"pseudo-identifiers\",\r\n \"label\": \"UUIDs or pseudo-identifiers instead of DB IDs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"opaqueIdentifiers\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-07\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"no-sensitive-data-in-urls\",\r\n \"label\": \"No sensitive data in URLs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"noSensitiveDataInPaths\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-06\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"http-methods-match-resources\",\r\n \"label\": \"HTTP methods only for intended resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"methodResourceConsistency\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\",\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4,\r\n \"items\": [\r\n {\r\n \"id\": \"design-items-audited\",\r\n \"label\": \"All prototype and design items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"design\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"design-reflects-business-value\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/production-readiness-review.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-validated-on-change\",\r\n \"label\": \"Spec validated on every change\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"validationWorkflowPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\",\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"schema-and-examples-pass\",\r\n \"label\": \"Schema and examples pass validation\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPassValidation\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-contract-tested\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\",\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"api-audit-checklist\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"uses-https\",\r\n \"label\": \"Uses HTTPS or encrypted protocols\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"auth-protection\",\r\n \"label\": \"Endpoints protected by authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"token-auth\",\r\n \"label\": \"Token-based authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"csrf-protection\",\r\n \"label\": \"Protected against CSRF\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-08\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-development-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"inputs-auto-validated\",\r\n \"label\": \"Inputs auto-validated by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"contract-first-design\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\",\r\n \"test\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"outputs-auto-escaped\",\r\n \"label\": \"Outputs auto-escaped by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"JSON APIs do not typically require output escaping in the same way as HTML rendering.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"encryption-in-transit\",\r\n \"label\": \"Encryption for data in transit and storage\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"infra-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"message-integrity\",\r\n \"label\": \"Message integrity implemented\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"monitoring\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5,\r\n \"items\": [\r\n {\r\n \"id\": \"published-via-api-management\",\r\n \"label\": \"Published via API management\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"ci-cd\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"visible-in-dev-portal\",\r\n \"label\": \"Visible in developer portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-community-engagement-strategies\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"docs-auto-generated\",\r\n \"label\": \"Docs auto-generated from spec and schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\",\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"documentation\",\r\n \"ci-cd\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/publishing/README.md\",\r\n \"docs/api/audit/design-audit.read-only.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-auto-updated\",\r\n \"label\": \"Spec auto-updated to gateway and dev portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"contract-first-design\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"gateway-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"official-domain\",\r\n \"label\": \"Published under official organization domain\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6,\r\n \"items\": []\r\n }\r\n ],\r\n \"guidelines\": [\r\n {\r\n \"id\": \"REST-CONTRACT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST implement endpoints, parameters, request bodies, response bodies, and error responses as defined in the validated OpenAPI contract.\",\r\n \"relatedAuditItems\": [\r\n \"spec-contains-schemas\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CONTRACT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST keep the implementation, published OpenAPI description, gateway configuration, and developer portal documentation aligned on every change.\",\r\n \"relatedAuditItems\": [\r\n \"docs-auto-generated\",\r\n \"spec-auto-updated\",\r\n \"spec-validated-on-change\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VALIDATION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate path parameters, query parameters, headers, and JSON request bodies against the OpenAPI schema before business processing.\",\r\n \"relatedAuditItems\": [\r\n \"mandatory-fields-specified\",\r\n \"400-errors-specific\",\r\n \"inputs-auto-validated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST expose business-oriented resources and attributes rather than raw backend tables, internal service payloads, or system-specific field names.\",\r\n \"relatedAuditItems\": [\r\n \"based-on-clear-business-needs\",\r\n \"hides-raw-backend-data\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST preserve validated meanings of entities, attributes, statuses, and source-of-truth rules across all endpoints and operations.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\",\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use descriptive English names for resources and attributes.\",\r\n \"relatedAuditItems\": [\r\n \"descriptive-english-naming\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST avoid unexplained acronyms in public field and resource names.\",\r\n \"relatedAuditItems\": [\r\n \"field-names-avoid-acronyms\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use ISO date-time values with timezone information where dates are exposed.\",\r\n \"relatedAuditItems\": [\r\n \"dates-use-iso\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API SHOULD use standard codes, controlled vocabularies, and standardized value sets where applicable.\",\r\n \"relatedAuditItems\": [\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST describe the business value and feature intent of each endpoint or capability.\",\r\n \"relatedAuditItems\": [\r\n \"endpoint-descriptions-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST include examples for endpoints, request bodies, response bodies, and key attributes.\",\r\n \"relatedAuditItems\": [\r\n \"examples-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API SHOULD use consistent pagination, filtering, sorting, and response conventions across resources.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-GET-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use GET for safe read-only operations and MUST NOT define a request body for GET operations.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-POST-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use POST for resource creation and other non-idempotent operations.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-PUT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use PUT only for full resource replacement.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-DELETE-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use DELETE to remove resources.\",\r\n \"relatedAuditItems\": [\r\n \"delete-for-remove\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PATH-01\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"resource-modeling\",\r\n \"requirement\": \"The REST API SHOULD keep endpoint paths shallow and avoid more than two resource or sub-resource levels unless explicitly justified.\",\r\n \"relatedAuditItems\": [\r\n \"paths-max-two-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-200-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 200 OK for successful reads and updates that include a response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"post-returns-200\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-201-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 201 Created and the created resource identifier when a new resource is created.\",\r\n \"relatedAuditItems\": [\r\n \"create-returns-identifiers\",\r\n \"post-returns-201\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 204 No Content for successful delete operations that do not return a body.\",\r\n \"relatedAuditItems\": [\r\n \"delete-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API SHOULD return 204 No Content for successful operations that intentionally return no response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-empty-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-400-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST define 400 Bad Request responses with specific and actionable validation error information.\",\r\n \"relatedAuditItems\": [\r\n \"400-errors-specific\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-401-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 401 Unauthorized for missing or invalid credentials.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-403-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 403 Forbidden for authenticated clients lacking sufficient permission.\",\r\n \"relatedAuditItems\": [\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VERSION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"versioning\",\r\n \"requirement\": \"The REST API MUST define a versioning strategy before production release, and the strategy MUST be supportable by the API gateway.\",\r\n \"relatedAuditItems\": [\r\n \"versioning-decided\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST require authentication for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use token-based authentication or another approved modern authentication mechanism for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"token-auth\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-03\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST enforce object-level and function-level authorization on every protected operation.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\",\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST mitigate OWASP API risks including broken object level authorization, broken function level authorization, injection, and unrestricted resource consumption.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"rate-limits-enforced\",\r\n \"no-sensitive-data-in-urls\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-05\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use HTTPS or another approved encrypted protocol for all traffic.\",\r\n \"relatedAuditItems\": [\r\n \"uses-https\",\r\n \"encryption-in-transit\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-06\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST NOT expose sensitive information in URLs, query strings, logs, or unnecessary response fields.\",\r\n \"relatedAuditItems\": [\r\n \"no-sensitive-data-in-urls\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-07\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API SHOULD use UUIDs or other non-sequential public identifiers where direct database identifiers would increase exposure risk.\",\r\n \"relatedAuditItems\": [\r\n \"pseudo-identifiers\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-08\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST implement CSRF protection where relevant to the authentication model and client interaction pattern.\",\r\n \"relatedAuditItems\": [\r\n \"csrf-protection\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST define and enforce rate limits, throttling, or quotas according to capacity expectations.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST implement resilience controls such as timeouts, fallback behavior, and degradation handling according to business impact.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-OBS-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"observability\",\r\n \"requirement\": \"The REST API MUST implement logs, metrics, and monitoring needed to observe validation failures, auth failures, traffic, latency, and dependency health.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published through an API management platform.\",\r\n \"relatedAuditItems\": [\r\n \"published-via-api-management\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be accessible only through approved API gateway paths and managed entry points.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API SHOULD be visible in a developer portal with documentation generated from the contract.\",\r\n \"relatedAuditItems\": [\r\n \"visible-in-dev-portal\",\r\n \"docs-auto-generated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published under an approved organizational domain.\",\r\n \"relatedAuditItems\": [\r\n \"official-domain\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate the specification, schema, and examples on every change.\",\r\n \"relatedAuditItems\": [\r\n \"spec-validated-on-change\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST pass concept, design, security, and production-readiness checks before release.\",\r\n \"relatedAuditItems\": [\r\n \"concept-items-audited\",\r\n \"design-items-audited\"\r\n ]\r\n }\r\n ]\r\n}\r\n", "draft": false } ], "promptIds": [ "security-specialist:facilitate-station", "security-specialist:use-resources", "security-specialist:next-actions" ] }, { "id": "partner-specialist", "stakeholderId": "partner-specialist", "title": "Gestor de parceiros ou fornecedores", "summary": "Coordena relações com parceiros, fornecedores ou prestadores externos que influenciam a estratégia e entrega da capacidade ou API.", "stakeholder": { "id": "partner-specialist", "sourceKey": "partner-specialist", "sourceStakeholderId": "partner-specialist", "title": "Gestor de parceiros ou fornecedores", "description": "Coordena relações com parceiros, fornecedores ou prestadores externos que influenciam a estratégia e entrega da capacidade ou API.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." } ], "stations": [ { "id": "api-publishing", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos." }, { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." }, { "id": "api-consumer-experience", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento." }, { "id": "api-delivery", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia." } ], "canvases": [ { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "capabilityBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da Capacidade" }, { "id": "consumerExperienceRequirementsCanvas", "title": "Canvas de Requisitos da Experiência do Utilizador" } ], "decisions": [ "Publicar APIs nos gateways e ambientes adequados para apoiar a reutilização por vários consumidores de API.", "Documentar a forma como os consumidores encontram e utilizam a API, incluindo processos de integração e registo.", "Garantir que os modelos de segurança, a configuração da porta de ligação e os termos legais sejam claros e acessíveis aos consumidores.", "Permitir que as APIs sejam publicadas no ambiente relevante e ter mecanismos claros de registo e acesso (por exemplo, chaves de API, OAuth, planos de subscrição), dependendo dos segmentos de consumidores de API e dos requisitos de segurança e conformidade.", "A publicação é mais do que a disponibilização - trata-se de capacidade de descoberta, acesso e suporte. Se as APIs não forem publicadas corretamente, não serão utilizadas, reutilizadas ou protegidas de forma eficaz.", "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente." ], "outputs": [ "APIs publicadas no ambiente correto (privado, parceiro, público)", "Processos claros de integração e registo da API", "Documentação, modelos e políticas de segurança disponíveis", "APIs prontas para escala e governação", "gateway-config", "developer-portal", "documentation", "release-record" ], "recommendedResources": [ { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "service-agreement-template", "slug": "resources/service-agreement-template", "title": "Modelo de contrato de serviço", "description": "Um formato de acordo personalizável que define expectativas, SLAs, responsabilidades e termos de acesso para o consumo de API.", "category": "guideline", "icon": "edit-document-outline", "order": 172, "outcomes": [ "Melhor compreensão dos princípios do modelo de contrato de prestação de serviços", "Abordagem normalizada utilizando o modelo de contrato de serviços", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Defina acordos de serviço que descrevam as expectativas, os níveis de serviço e as responsabilidades de cada API.", "Utilize formatos normalizados para criar contratos de serviço legíveis por máquina que sejam fáceis de partilhar e validar.", "Assegurar que os acordos de serviço são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityBusinessModelCanvas", "slug": "resources/capability-business-model-canvas", "title": "Canvas do Modelo de Negócio da Capacidade", "description": "Um canvas de modelo de negócio para capacidades de integração reutilizáveis, cobrindo valor, utilizadores, propriedade, envolvimento, custos e benefícios sem assumir disponibilização por API.", "category": "canvas", "icon": "dashboard-outline", "order": 3.1, "outcomes": [ "Modelo operacional viável para a capacidade reutilizável", "Propriedade, utilizadores, canais, parceiros e necessidades de suporte clarificados", "Custos e benefícios visíveis antes do compromisso com a arquitetura" ], "steps": [ "Resuma a proposta de valor da capacidade.", "Identifique segmentos de utilizadores e canais de envolvimento.", "Defina atividades, recursos e parceiros-chave.", "Capte custos e benefícios.", "Clarifique propriedade, financiamento, suporte e expectativas de ciclo de vida.", "Valide o modelo com utilizadores, produtores e partes interessadas de governação." ], "canvasId": "capabilityBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-development-best-practices", "slug": "resources/api-development-best-practices", "title": "Boas práticas de desenvolvimento de API", "description": "Orientações de implementação para transformar um contrato de interface da API validado numa base de código de API consistente e sustentável, utilizando bibliotecas padrão, padrões reutilizáveis e fluxos de trabalho de desenvolvimento alinhados.", "category": "guideline", "icon": "edit-document-outline", "order": 112, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de desenvolvimento de API", "Abordagem normalizada utilizando as boas práticas de desenvolvimento de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplique essas práticas ao contrato de interface da API validado e ao plano de implementação antes do início da codificação.", "Utilize frameworks, bibliotecas e padrões de codificação estabelecidos para implementar o contrato de forma consistente e sustentável." ], "canvasId": null, "sourcePath": "src/snippets/pt/api-design-principles-guidance.md", "sourceUrl": null, "contentMarkdown": "## Como iniciar o trabalho de entrega da API com base nas fases anteriores (“etapas”)\r\nUtilize estas orientações no início da `API Delivery` (entrega da API), após a revisão e aceitação do contrato da API (por exemplo, OpenAPI) e dos principais resultados das etapas anteriores.\r\nO objetivo não é desenvolver a implementação de forma isolada. O objetivo é transformar os resultados acordados nas etapas anteriores em uma estrutura de código concreta, regras de validação, comportamento em tempo de execução e decisões relativas à entrega do produto API.\r\n\r\n---\r\n\r\n### 1. Comece a partir do contrato validado\r\n- Trate o contrato de API validado como o principal ponto de referência para as decisões de implementação.\r\n- Mantenha o contrato e a implementação alinhados ao longo de toda a entrega do produto API.\r\n- Use o contrato para orientar a validação de solicitações, o mapeamento de respostas, a documentação e os testes.\r\n\r\n---\r\n\r\n### 2. Use os resultados do domínio para preservar o significado comercial\r\n- Use os resultados do `Domain Canvas` para orientar a nomenclatura, como a implementação é dividida em responsabilidades comerciais claras e como diferentes sistemas de back-end são conectados sem expor suas diferenças.\r\n- Preserve os significados validados de entidades, atributos, status e regras de fonte de verdade.\r\n- Evite vazar modelos específicos do back-end ou inconsistências para a API pública.\r\n\r\n---\r\n\r\n### 3. Use os resultados da jornada para preservar fluxos críticos\r\n- Use os resultados do `Customer Journey Canvas` para identificar quais fluxos de usuários são mais importantes para serem atendidos primeiro.\r\n- Use os resultados da `API Consumer Experience` para manter a API compreensível, previsível e fácil de integrar.\r\n- Deixe que as prioridades de jornada acordadas decidam quais caminhos de implementação precisam da maior confiabilidade, menor latência, erros mais claros e maior foco operacional.\r\n\r\n---\r\n\r\n### 4. Use os resultados da Proposta de Valor para preservar o valor para o consumidor\r\n- Use os resultados do `API Value Proposition Canvas` para manter a implementação focada nas dores, ganhos e recursos da API acordados.\r\n- Preserve os significados dos campos, o comportamento e as promessas que tornaram a API valiosa nas etapas anteriores.\r\n- Garanta que o tratamento de erros, a atualização e a nomenclatura apoiem tanto a experiência do desenvolvedor pretendida quanto o caso de uso de negócios.\r\n\r\n---\r\n\r\n### 5. Use os resultados da arquitetura para moldar as decisões de tempo de execução\r\n- Use os resultados do `Business Impact Canvas` para orientar as decisões sobre resiliência, tempo limite, fallback e degradação.\r\n- Use os resultados do `Locations Canvas` para orientar os limites de rede, limites de confiança, caminhos de acesso e restrições de implantação.\r\n- Use os resultados do `Capacity Canvas` para orientar limites de taxa, cache, escalonamento e comportamento em picos de carga.\r\n- Use as orientações do `API Metrics And Analytics` para decidir o que deve ser observado desde a primeira implementação em diante.\r\n\r\n---\r\n\r\n### 6. Use os resultados do projeto de interação e protocolo para moldar a estrutura do código\r\n- Use os resultados do `Interaction Canvas` para evitar implementar estilos de interação não suportados prematuramente.\r\n- Use os resultados do projeto `REST`, `Event` ou `GraphQL` para moldar o comportamento de solicitação, resposta e validação específico do protocolo.\r\n- Reflete o estilo de interação selecionado claramente na estrutura do código, nas responsabilidades e na estratégia de testes.\r\n\r\n---\r\n\r\n### 7. Usa os resultados da auditoria para melhorar a entrega antes que a codificação avance demais\r\n- Usa as conclusões da auditoria para remover ambiguidades antes que a implementação se espalhe pela base de código.\r\n- Corrige regras de solicitação pouco claras, validações ausentes, contratos de erro fracos e lacunas operacionais logo no início.\r\n- Trate a auditoria como um ciclo de melhoria de projeto antes da produção, não apenas como uma etapa de decisão final.\r\n\r\n---\r\n\r\n### 8. Aplique as orientações e, em seguida, resuma\r\n- Aplique estas orientações à API atual e ao plano de implementação.\r\n- Resuma as implicações para a estrutura do código, validação de solicitações, integração de fontes, segurança, monitoramento e alertas, e testes.\r\n- Não crie um artefato de entrega separado, a menos que a equipe ou o usuário precise especificamente de um.\r\n", "draft": true }, { "id": "api-testing-best-practices", "slug": "resources/api-testing-best-practices", "title": "Boas práticas de teste de API", "description": "Diretrizes para a implementação de testes automatizados funcionais, de desempenho e de segurança ao longo do ciclo de vida da API.", "category": "guideline", "icon": "edit-document-outline", "order": 133, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de teste de API", "Abordagem normalizada utilizando as boas práticas de teste de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Integrar testes funcionais e não funcionais no pipeline CI/CD para garantir que as APIs cumprems normas de qualidade.", "Utilizar ferramentas de teste automatizadas para validar a funcionalidade, a segurança e o desempenho da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "apiops-CI-CD-for-apis", "slug": "resources/apiops-CI-CD-for-apis", "title": "APIOps CI/CD para APIs", "description": "Orientação de disponibilização que integra tarefas do ciclo de vida da API - design, teste, governação - em pipelines de integração e entrega contínuas.", "category": "guideline", "icon": "edit-document-outline", "order": 140, "outcomes": [ "Melhor compreensão dos princípios de CI/CD para APIs", "Abordagem normalizada utilizando CI/CD para APIs", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilizar pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "promptIds": [ "partner-specialist:facilitate-station", "partner-specialist:use-resources", "partner-specialist:next-actions" ] }, { "id": "customer-specialist", "stakeholderId": "customer-specialist", "title": "Representante de cliente ou parceiro", "summary": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "stakeholder": { "id": "customer-specialist", "sourceKey": "customer-specialist", "sourceStakeholderId": "customer-specialist", "title": "Representante de cliente ou parceiro", "description": "Contribui com a perspetiva do cliente ou parceiro para o percurso, valor e modelo de colaboração.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." }, { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." }, { "id": "api-consumer-experience", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento." } ], "canvases": [ { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "capabilityBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da Capacidade" }, { "id": "consumerExperienceRequirementsCanvas", "title": "Canvas de Requisitos da Experiência do Utilizador" }, { "id": "apiValuePropositionCanvas", "title": "Canvas da Proposta de Valor da API" }, { "id": "apiBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da API" } ], "decisions": [ "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais." ], "outputs": [ "Uma proposta de valor e um público-alvo da API simples", "Linguagem partilhada entre o produto, a conceção e a tecnologia", "Um argumento sólido ou um caso para financiamento/aprovação", "design-artifact", "documentation", "research", "roadmap", "Identifique e dê prioridade aos seus consumidores de API" ], "recommendedResources": [ { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityBusinessModelCanvas", "slug": "resources/capability-business-model-canvas", "title": "Canvas do Modelo de Negócio da Capacidade", "description": "Um canvas de modelo de negócio para capacidades de integração reutilizáveis, cobrindo valor, utilizadores, propriedade, envolvimento, custos e benefícios sem assumir disponibilização por API.", "category": "canvas", "icon": "dashboard-outline", "order": 3.1, "outcomes": [ "Modelo operacional viável para a capacidade reutilizável", "Propriedade, utilizadores, canais, parceiros e necessidades de suporte clarificados", "Custos e benefícios visíveis antes do compromisso com a arquitetura" ], "steps": [ "Resuma a proposta de valor da capacidade.", "Identifique segmentos de utilizadores e canais de envolvimento.", "Defina atividades, recursos e parceiros-chave.", "Capte custos e benefícios.", "Clarifique propriedade, financiamento, suporte e expectativas de ciclo de vida.", "Valide o modelo com utilizadores, produtores e partes interessadas de governação." ], "canvasId": "capabilityBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "apiValuePropositionCanvas", "slug": "resources/api-value-proposition-canvas", "title": "Canvas da Proposta de Valor da API", "description": "Alinhar as funcionalidades da API com as necessidades dos utilizadores, mapeando tarefas, problemas e ganhos para os produtos da API.", "category": "canvas", "icon": "dashboard-outline", "order": 2, "outcomes": [ "Desenvolvimento de funcionalidades específicas", "Alinhamento com as necessidades dos utilizadores", "Melhoria da satisfação do utilizador da API" ], "steps": [ "Listar as tarefas do percurso do utilizador", "Identificar as características que proporcionam os ganhos esperados", "Definir características para enfrentar os desafios", "Mapear características para produtos API" ], "canvasId": "apiValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "apiBusinessModelCanvas", "slug": "resources/api-business-model-canvas", "title": "Canvas do Modelo de Negócio da API", "description": "Avaliar estrategicamente a viabilidade do negócio de API, mapeando propostas de valor, segmentos de utilizadores e recursos-chave.", "category": "canvas", "icon": "dashboard-outline", "order": 3, "outcomes": [ "Estratégia comercial clara para APIs", "Identificação dos principais recursos e parceiros", "Alinhamento das características da API com os objetivos de negócio" ], "steps": [ "Resumir a proposta de valor da API", "Definir segmentos de utilizadores", "Identificar estratégias de relações com os promotores", "Mapear os canais de distribuição", "documentar os principais recursos e actividades", "Identificar os principais parceiros e partes interessadas", "Destacar os benefícios e os custos" ], "canvasId": "apiBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false } ], "promptIds": [ "customer-specialist:facilitate-station", "customer-specialist:use-resources", "customer-specialist:next-actions" ] }, { "id": "api-consumer-specialist", "stakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "summary": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "stakeholder": { "id": "api-consumer-specialist", "sourceKey": "api-consumer-specialist", "sourceStakeholderId": "api-consumer-specialist", "title": "Representante dos utilizadores da API", "description": "Representa as necessidades de programadores, integradores ou outros utilizadores que utilizam a API diretamente.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." }, { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-consumer-experience", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento." }, { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." }, { "id": "api-publishing", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." }, { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." }, { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." } ], "canvases": [ { "id": "consumerExperienceRequirementsCanvas", "title": "Canvas de Requisitos da Experiência do Utilizador" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "interactionCanvas", "title": "Canvas de Interação" }, { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "capabilityBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da Capacidade" }, { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" }, { "id": "apiValuePropositionCanvas", "title": "Canvas da Proposta de Valor da API" }, { "id": "restCanvas", "title": "Canvas REST" }, { "id": "eventCanvas", "title": "Canvas de Eventos" }, { "id": "graphqlCanvas", "title": "Canvas GraphQL" }, { "id": "apiBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da API" } ], "decisions": [ "Analise o Canvas da Proposta de Valor da API existente sob a perspectiva do consumidor da API. Mantenha as tarefas de negócios suportadas estáveis ​​e enriqueça os recursos que aliviam problemas e possibilitam ganhos com as preocupações do consumidor da API, para que elas possam orientar as decisões de conceção futuras.", "Utilize o Canvas do Percurso do Cliente para a jornada do consumidor da API, desde a descoberta e avaliação até a integração, resolução de problemas e uso contínuo.", "Utilize a jornada resultante para melhorar a integração, a documentação, o suporte e os ciclos de feedback para o consumidor da API.", "Fornecer diretrizes, ferramentas e mecanismos de feedback para compreender, analisar e melhorar a experiência interna e externa dos programadores e parceiros.", "As APIs excelentes não funcionam apenas - elas são intuitivas. Quer o consumidor seja um programador interno, um parceiro externo ou um agente de IA, a sua experiência determina a adoção.\n\nSnum plano de experiência claro:\n- Grandes APIs ficam sem uso\n- As equipas perdem tempo a tentar adivinhar como utilizar a sua API\n- Os ciclos de feedback estão quebrados ou ausentes.\n\nEsta estação ajuda-o a ver a sua API através dos olhos dos seus consumidores.", "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "outputs": [ "Identifique e dê prioridade aos seus consumidores de API", "Definir o percurso da experiência API", "Planeamento da integração, documentação e feedback", "Melhorar a adoção através de empatia genuína + Experiência do Programador (DX)", "design-artifact", "documentation", "consumer-feedback", "Conceção de API bem documentada e coerente" ], "recommendedResources": [ { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "contract-first-design", "slug": "resources/contract-first-design", "title": "Primeira conceção do contrato", "description": "Uma diretriz que defende abordagens API-first utilizando contratos formais (por exemplo, OpenAPI) para alinhar as partes interessadas antes do desenvolvimento.", "category": "guideline", "icon": "edit-document-outline", "order": 146, "outcomes": [ "Melhor compreensão dos princípios de conceção da primeira fase do contrato", "Abordagem normalizada utilizando a conceção orientada por contrato", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar." ], "canvasId": null, "sourcePath": "src/snippets/api-contract-example.yaml", "sourceUrl": null, "contentMarkdown": "openapi: 3.0.3\r\ninfo:\r\n title: Sample Catalog API\r\n version: 1.0.0\r\n description: |\r\n Starter example for a read-only APIOps Cycles API.\r\n This example keeps the contract audit-friendly and easy to extend.\r\nservers:\r\n - url: /v1\r\n description: Versioned API base path\r\ntags:\r\n - name: catalog\r\n description: Browse and search catalog items\r\npaths:\r\n /items:\r\n get:\r\n tags: [catalog]\r\n summary: List catalog items\r\n description: Returns a paginated list of public catalog items.\r\n operationId: listItems\r\n parameters:\r\n - $ref: \"#/components/parameters/searchTerm\"\r\n - $ref: \"#/components/parameters/categoryId\"\r\n - $ref: \"#/components/parameters/page\"\r\n - $ref: \"#/components/parameters/pageSize\"\r\n responses:\r\n \"200\":\r\n description: Item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n examples:\r\n default:\r\n value:\r\n data:\r\n - itemId: item-123\r\n slug: blue-widget\r\n name: Blue Widget\r\n status: published\r\n page:\r\n number: 1\r\n size: 20\r\n totalItems: 1\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"429\":\r\n $ref: \"#/components/responses/TooManyRequests\"\r\n /items/{itemId}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by id\r\n description: Returns a single public catalog item by opaque identifier.\r\n operationId: getItemById\r\n parameters:\r\n - $ref: \"#/components/parameters/itemId\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /items/by-slug/{slug}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by slug\r\n description: Returns a single item by public slug.\r\n operationId: getItemBySlug\r\n parameters:\r\n - $ref: \"#/components/parameters/slug\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /categories/{categoryId}/items:\r\n get:\r\n tags: [catalog]\r\n summary: List items in category\r\n description: Returns public items in a category.\r\n operationId: listItemsByCategory\r\n parameters:\r\n - $ref: \"#/components/parameters/categoryId\"\r\n responses:\r\n \"200\":\r\n description: Category item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\ncomponents:\r\n parameters:\r\n itemId:\r\n name: itemId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: item-123\r\n slug:\r\n name: slug\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9]+(?:-[a-z0-9]+)*$\"\r\n example: blue-widget\r\n categoryId:\r\n name: categoryId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: home-goods\r\n searchTerm:\r\n name: searchTerm\r\n in: query\r\n required: false\r\n schema:\r\n type: string\r\n minLength: 1\r\n example: widget\r\n page:\r\n name: page\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n default: 1\r\n pageSize:\r\n name: pageSize\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n maximum: 100\r\n default: 20\r\n responses:\r\n BadRequest:\r\n description: Validation failed\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n examples:\r\n default:\r\n value:\r\n code: BAD_REQUEST\r\n message: Invalid request\r\n NotFound:\r\n description: Resource not found\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n TooManyRequests:\r\n description: Rate limit exceeded\r\n headers:\r\n Retry-After:\r\n schema:\r\n type: integer\r\n description: Seconds until the next allowed request.\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n schemas:\r\n ItemListResponse:\r\n type: object\r\n required: [data, page]\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/ItemSummary\"\r\n page:\r\n $ref: \"#/components/schemas/Page\"\r\n ItemSummary:\r\n type: object\r\n required: [itemId, slug, name, status]\r\n properties:\r\n itemId:\r\n type: string\r\n slug:\r\n type: string\r\n name:\r\n type: string\r\n status:\r\n type: string\r\n enum: [published, hidden]\r\n ItemDetail:\r\n allOf:\r\n - $ref: \"#/components/schemas/ItemSummary\"\r\n - type: object\r\n properties:\r\n description:\r\n type: string\r\n categories:\r\n type: array\r\n items:\r\n type: string\r\n variants:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/Variant\"\r\n Variant:\r\n type: object\r\n required: [variantId, sku, price, inventory]\r\n properties:\r\n variantId:\r\n type: string\r\n sku:\r\n type: string\r\n price:\r\n $ref: \"#/components/schemas/Price\"\r\n inventory:\r\n $ref: \"#/components/schemas/Inventory\"\r\n Price:\r\n type: object\r\n required: [amount, currency]\r\n properties:\r\n amount:\r\n type: number\r\n format: decimal\r\n currency:\r\n type: string\r\n example: EUR\r\n Inventory:\r\n type: object\r\n required: [available]\r\n properties:\r\n available:\r\n type: integer\r\n minimum: 0\r\n reserved:\r\n type: integer\r\n minimum: 0\r\n source:\r\n type: string\r\n Page:\r\n type: object\r\n required: [number, size, totalItems]\r\n properties:\r\n number:\r\n type: integer\r\n size:\r\n type: integer\r\n totalItems:\r\n type: integer\r\n ErrorResponse:\r\n type: object\r\n required: [code, message]\r\n properties:\r\n code:\r\n type: string\r\n message:\r\n type: string\r\n", "draft": true }, { "id": "service-agreement-template", "slug": "resources/service-agreement-template", "title": "Modelo de contrato de serviço", "description": "Um formato de acordo personalizável que define expectativas, SLAs, responsabilidades e termos de acesso para o consumo de API.", "category": "guideline", "icon": "edit-document-outline", "order": 172, "outcomes": [ "Melhor compreensão dos princípios do modelo de contrato de prestação de serviços", "Abordagem normalizada utilizando o modelo de contrato de serviços", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Defina acordos de serviço que descrevam as expectativas, os níveis de serviço e as responsabilidades de cada API.", "Utilize formatos normalizados para criar contratos de serviço legíveis por máquina que sejam fáceis de partilhar e validar.", "Assegurar que os acordos de serviço são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-metrics-and-analytics", "slug": "resources/api-metrics-and-analytics", "title": "Métricas e análise de API", "description": "Um recurso para definir, recolher e analisar o desempenho da API e os dados de utilização para alinhar os KPIs técnicos com os resultados de negócio.", "category": "guideline", "icon": "edit-document-outline", "order": 119, "outcomes": [ "Melhor compreensão dos princípios de métrica e análise de API", "Abordagem normalizada utilizando métricas e análise de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação" ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-community-engagement-strategies", "slug": "resources/api-community-engagement-strategies", "title": "Estratégias de envolvimento da comunidade API", "description": "Um manual para promover a adoção de APIs, cultivando comunidades através de conteúdos, canais de apoio, ciclos de feedback e estratégias de envolvimento social.", "category": "guideline", "icon": "edit-document-outline", "order": 103, "outcomes": [ "Melhor compreensão dos princípios das estratégias de envolvimento da comunidade da API", "Abordagem normalizada utilizando as estratégias de envolvimento da comunidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Desenvolver estratégias de marketing para promover as APIs junto de públicos-alvo, incluindo redes sociais, blogues e webinars.", "Criar materiais promocionais (por exemplo, estudos de casos, histórias de sucesso) que realcem o valor e as vantagens das APIs.", "Criar materiais educativos (por exemplo, tutoriais, documentação) que expliquem as características, as vantagens e os padrões de utilização da API.", "Interagir com os utilizadores da API através de ciclos de feedback, canais de apoio e fóruns da comunidade para compreender as suas necessidades e melhorar a adoção da API.", "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false } ], "promptIds": [ "api-consumer-specialist:facilitate-station", "api-consumer-specialist:use-resources", "api-consumer-specialist:next-actions" ] }, { "id": "business-owner", "stakeholderId": "business-owner", "title": "Responsável de negócio", "summary": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "stakeholder": { "id": "business-owner", "sourceKey": "business-owner", "sourceStakeholderId": "business-owner", "title": "Responsável de negócio", "description": "Representa os objetivos de negócio, o financiamento e os resultados esperados da iniciativa de capacidade, API ou automatização.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." }, { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." }, { "id": "api-consumer-experience", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento." }, { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." }, { "id": "api-publishing", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." }, { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." }, { "id": "api-delivery", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia." }, { "id": "api-audit", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição." } ], "canvases": [ { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "capabilityBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da Capacidade" }, { "id": "consumerExperienceRequirementsCanvas", "title": "Canvas de Requisitos da Experiência do Utilizador" }, { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" }, { "id": "interactionCanvas", "title": "Canvas de Interação" }, { "id": "apiValuePropositionCanvas", "title": "Canvas da Proposta de Valor da API" }, { "id": "apiBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da API" }, { "id": "restCanvas", "title": "Canvas REST" }, { "id": "eventCanvas", "title": "Canvas de Eventos" }, { "id": "graphqlCanvas", "title": "Canvas GraphQL" } ], "decisions": [ "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais." ], "outputs": [ "Uma proposta de valor e um público-alvo da API simples", "Linguagem partilhada entre o produto, a conceção e a tecnologia", "Um argumento sólido ou um caso para financiamento/aprovação", "design-artifact", "documentation", "research", "roadmap", "Identifique e dê prioridade aos seus consumidores de API" ], "recommendedResources": [ { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityBusinessModelCanvas", "slug": "resources/capability-business-model-canvas", "title": "Canvas do Modelo de Negócio da Capacidade", "description": "Um canvas de modelo de negócio para capacidades de integração reutilizáveis, cobrindo valor, utilizadores, propriedade, envolvimento, custos e benefícios sem assumir disponibilização por API.", "category": "canvas", "icon": "dashboard-outline", "order": 3.1, "outcomes": [ "Modelo operacional viável para a capacidade reutilizável", "Propriedade, utilizadores, canais, parceiros e necessidades de suporte clarificados", "Custos e benefícios visíveis antes do compromisso com a arquitetura" ], "steps": [ "Resuma a proposta de valor da capacidade.", "Identifique segmentos de utilizadores e canais de envolvimento.", "Defina atividades, recursos e parceiros-chave.", "Capte custos e benefícios.", "Clarifique propriedade, financiamento, suporte e expectativas de ciclo de vida.", "Valide o modelo com utilizadores, produtores e partes interessadas de governação." ], "canvasId": "capabilityBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "service-agreement-template", "slug": "resources/service-agreement-template", "title": "Modelo de contrato de serviço", "description": "Um formato de acordo personalizável que define expectativas, SLAs, responsabilidades e termos de acesso para o consumo de API.", "category": "guideline", "icon": "edit-document-outline", "order": 172, "outcomes": [ "Melhor compreensão dos princípios do modelo de contrato de prestação de serviços", "Abordagem normalizada utilizando o modelo de contrato de serviços", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Defina acordos de serviço que descrevam as expectativas, os níveis de serviço e as responsabilidades de cada API.", "Utilize formatos normalizados para criar contratos de serviço legíveis por máquina que sejam fáceis de partilhar e validar.", "Assegurar que os acordos de serviço são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "promptIds": [ "business-owner:facilitate-station", "business-owner:use-resources", "business-owner:next-actions" ] }, { "id": "automation-owner", "stakeholderId": "automation-owner", "title": "Responsável pela automatização", "summary": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "stakeholder": { "id": "automation-owner", "sourceKey": "automation-owner", "sourceStakeholderId": "automation-owner", "title": "Responsável pela automatização", "description": "Responsável pelos objetivos, valor de negócio, prioridades, controlos e resultados do ciclo de vida da automatização.", "involvement": "" }, "cycles": [ { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." }, { "id": "api-consumer-experience", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento." }, { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." }, { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." }, { "id": "api-delivery", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia." }, { "id": "api-audit", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição." }, { "id": "api-publishing", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." } ], "canvases": [ { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "consumerExperienceRequirementsCanvas", "title": "Canvas de Requisitos da Experiência do Utilizador" }, { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" }, { "id": "interactionCanvas", "title": "Canvas de Interação" } ], "decisions": [ "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais." ], "outputs": [ "Uma proposta de valor e um público-alvo da API simples", "Linguagem partilhada entre o produto, a conceção e a tecnologia", "Um argumento sólido ou um caso para financiamento/aprovação", "design-artifact", "documentation", "research", "roadmap", "Identifique e dê prioridade aos seus consumidores de API" ], "recommendedResources": [ { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "automation-operational-ownership-guide", "slug": "resources/automation-operational-ownership-guide", "title": "Guia de responsabilidade operacional da automatização", "description": "Orientação para definir responsabilidade, runbooks, supervisão, suporte, monitorização, controlo de alterações e responsabilidades de melhoria contínua para automatizações.", "category": "guideline", "icon": "edit-document-outline", "order": 185, "outcomes": [ "Modelo operacional claro para a automatização", "Responsabilidades de propriedade, suporte e escalamento atribuídas", "Práticas de monitorização e alteração prontas para operação em produção" ], "steps": [ "Defina responsáveis de negócio, técnicos e operacionais pela automatização.", "Documente runbooks, caminhos de suporte, sinais de monitorização, expectativas de serviço e regras de escalamento.", "Defina controlo de alterações e práticas de revisão para atualizações de workflow, plataforma e regras." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "process-workflow-design-guide", "slug": "resources/process-workflow-design-guide", "title": "Guia de desenho do processo e workflow", "description": "Orientação para modelar passos do processo, papéis, passagens de responsabilidade, pontos de decisão, estados, entradas, saídas e exceções que moldam um workflow de automatização.", "category": "guideline", "icon": "edit-document-outline", "order": 181, "outcomes": [ "Desenho claro do workflow de automatização", "Passos do processo e passagens de responsabilidade documentados antes da implementação", "Estados do workflow, entradas, saídas e caminhos de exceção compreendidos" ], "steps": [ "Mapeie o fluxo do processo atual e alvo, incluindo responsabilidades humanas e dos sistemas.", "Identifique gatilhos do workflow, estados, decisões, entradas de dados, saídas e critérios de conclusão.", "Documente passagens de responsabilidade entre utilizadores, sistemas, operações e papéis de suporte.", "Confirme que passos devem ser automatizados e quais exigem julgamento humano." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "promptIds": [ "automation-owner:facilitate-station", "automation-owner:use-resources", "automation-owner:next-actions" ] }, { "id": "capability-owner", "stakeholderId": "capability-owner", "title": "Responsável pela capacidade", "summary": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "stakeholder": { "id": "capability-owner", "sourceKey": "capability-owner", "sourceStakeholderId": "capability-owner", "title": "Responsável pela capacidade", "description": "Responsável pela visão, valor, prioridades, ciclo de vida e reutilização da capacidade junto dos utilizadores.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." } ], "stations": [ { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." }, { "id": "api-consumer-experience", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento." }, { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." }, { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." }, { "id": "api-delivery", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia." }, { "id": "api-audit", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição." }, { "id": "api-publishing", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." } ], "canvases": [ { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "capabilityBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da Capacidade" }, { "id": "consumerExperienceRequirementsCanvas", "title": "Canvas de Requisitos da Experiência do Utilizador" }, { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" }, { "id": "interactionCanvas", "title": "Canvas de Interação" }, { "id": "restCanvas", "title": "Canvas REST" }, { "id": "eventCanvas", "title": "Canvas de Eventos" }, { "id": "graphqlCanvas", "title": "Canvas GraphQL" } ], "decisions": [ "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais." ], "outputs": [ "Uma proposta de valor e um público-alvo da API simples", "Linguagem partilhada entre o produto, a conceção e a tecnologia", "Um argumento sólido ou um caso para financiamento/aprovação", "design-artifact", "documentation", "research", "roadmap", "Identifique e dê prioridade aos seus consumidores de API" ], "recommendedResources": [ { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityBusinessModelCanvas", "slug": "resources/capability-business-model-canvas", "title": "Canvas do Modelo de Negócio da Capacidade", "description": "Um canvas de modelo de negócio para capacidades de integração reutilizáveis, cobrindo valor, utilizadores, propriedade, envolvimento, custos e benefícios sem assumir disponibilização por API.", "category": "canvas", "icon": "dashboard-outline", "order": 3.1, "outcomes": [ "Modelo operacional viável para a capacidade reutilizável", "Propriedade, utilizadores, canais, parceiros e necessidades de suporte clarificados", "Custos e benefícios visíveis antes do compromisso com a arquitetura" ], "steps": [ "Resuma a proposta de valor da capacidade.", "Identifique segmentos de utilizadores e canais de envolvimento.", "Defina atividades, recursos e parceiros-chave.", "Capte custos e benefícios.", "Clarifique propriedade, financiamento, suporte e expectativas de ciclo de vida.", "Valide o modelo com utilizadores, produtores e partes interessadas de governação." ], "canvasId": "capabilityBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false } ], "promptIds": [ "capability-owner:facilitate-station", "capability-owner:use-resources", "capability-owner:next-actions" ] }, { "id": "governance-specialist", "stakeholderId": "governance-specialist", "title": "Responsável pela governação API", "summary": "Representa práticas de revisão, auditoria e governação em toda a organização para qualidade e conformidade das APIs.", "stakeholder": { "id": "governance-specialist", "sourceKey": "governance-specialist", "sourceStakeholderId": "governance-specialist", "title": "Responsável pela governação API", "description": "Representa práticas de revisão, auditoria e governação em toda a organização para qualidade e conformidade das APIs.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." }, { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-audit", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição." } ], "canvases": [], "decisions": [ "Realizar auditorias para garantir que as APIs cumprems normas organizacionais, técnicas e legais antes da publicação.", "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas.", "Colaborar com as equipas de governação e especialistas no domínio para garantir que as APIs estão prontas para produção.", "Estabeleça um processo de auditoria consistente que avalie a prontidão da API em todas as etapas do ciclo de vida usando critérios, evidências e padrões definidos. Garanta que as lacunas sejam identificadas antecipadamente e resolvidas antes da publicação.", "As APIs são produtos de longa duração e devem atender às expectativas de qualidade, consistência e conformidade. A auditoria conecta as decisões de conceção, a implementação e a prontidão operacional a padrões definidos, reduzindo o risco antes da exposição." ], "outputs": [ "As APIs cumprems normas internas e externas", "Documentação clara das decisões de conceção e implementação da API", "Segurança, desempenho e conformidade validados", "Redução do risco de problemas na produção", "audit-report", "compliance-report", "security-report", "test-report" ], "recommendedResources": [ { "id": "api-audit-checklist", "slug": "resources/api-audit-checklist", "title": "Lista de verificação de auditoria da API", "description": "Uma lista de verificação baseada no ciclo de vida para verificar a prontidão da API em design, entrega, publicação e conformidade utilizando critérios de auditoria e evidências definidos.", "category": "checklist", "icon": "check-box-outline", "order": 13, "outcomes": [ "Melhor compreensão dos princípios da lista de controlo de auditoria da API", "Abordagem normalizada utilizando a lista de verificação de auditoria da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilize a lista de verificação de auditoria da API para garantir que a conceção da API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Realize auditorias para avaliar a cobertura do ciclo de vida e verificar se a API satisfaz os padrões de negócio, conceção e operacionais.", "Certifique-se de que a documentação, os modelos de segurança, a configuração do gateway e os requisitos legais estejam claramente definidos, validados e comprovados por evidências." ], "canvasId": null, "sourcePath": "src/snippets/api-audit-checklist.json", "sourceUrl": null, "contentMarkdown": "{\r\n \"profiles\": {\r\n \"read-only\": {\r\n \"description\": \"API profile that is read-only and does not allow create, update, or delete operations.\"\r\n },\r\n \"full-crud\": {\r\n \"description\": \"General API profile that allows create, update, and delete operations.\"\r\n }\r\n },\r\n \"lifecycleStages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6\r\n }\r\n ],\r\n \"stages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1,\r\n \"items\": [\r\n {\r\n \"id\": \"based-on-clear-business-needs\",\r\n \"label\": \"API is based on clear business needs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiBusinessModelCanvas\",\r\n \"apiValuePropositionCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"design-artifact\",\r\n \"documentation\",\r\n \"research\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\",\r\n \"specs/canvases/api-product-strategy/apiBusinessModelCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"concept-items-audited\",\r\n \"label\": \"All concept checklist items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"strategy\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\",\r\n \"api-opportunity-documented\",\r\n \"api-reusability\",\r\n \"value-prop-validated\",\r\n \"consumer-segments-identified\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/concept-review-report.json\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2,\r\n \"items\": [\r\n {\r\n \"id\": \"versioning-decided\",\r\n \"label\": \"Versioning strategy decided and supported by gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VERSION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-versioning-best-practices\",\r\n \"apiops-CI-CD-for-apis\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"ci-cd\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"only-via-gateway\",\r\n \"label\": \"Only accessible via API gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-02\",\r\n \"REST-CAPACITY-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"businessImpactCanvas\",\r\n \"locationsCanvas\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"infra-config\",\r\n \"security-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"rate-limits-enforced\",\r\n \"label\": \"Rate limits are enforced\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CAPACITY-01\",\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"capacityCanvas\",\r\n \"api-security-best-practices\",\r\n \"scalable-infrastructure-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"runtime\",\r\n \"monitoring\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-platform-architecture/capacityCanvas.empty.json\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3,\r\n \"items\": [\r\n {\r\n \"id\": \"endpoint-descriptions-present\",\r\n \"label\": \"Endpoints have business value and feature descriptions\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"operationDescriptions\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\",\r\n \"api-opportunity-documented\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiValuePropositionCanvas\",\r\n \"customerJourneyCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"hides-raw-backend-data\",\r\n \"label\": \"API hides raw backend data and is designed for shared use\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"interactionCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/domainCanvas.empty.json\",\r\n \"specs/canvases/api-design/interactionCanvas.empty.json\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"design-consistent\",\r\n \"label\": \"API design is consistent with other APIs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-02\",\r\n \"REST-CX-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-design/restCanvas.empty.json\",\r\n \"docs/api/design/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"descriptive-english-naming\",\r\n \"label\": \"Data and attribute naming uses descriptive English\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"fieldNamesDescriptive\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"mandatory-fields-specified\",\r\n \"label\": \"Mandatory fields are specified\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"requiredFieldsPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"dates-use-iso\",\r\n \"label\": \"Dates use ISO format with timezone\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"dateFormatTimezone\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"general-data-uses-standard-values\",\r\n \"label\": \"General data uses standard values\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"standardizedEnumsOrPatterns\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"field-names-avoid-acronyms\",\r\n \"label\": \"Field names avoid acronyms and use full words\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"avoidAcronyms\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"create-returns-identifiers\",\r\n \"label\": \"Creating new resources returns identifiers\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is read-only and does not create resources.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"paths-max-two-resources\",\r\n \"label\": \"Endpoint paths contain max two resources or sub-resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"pathDepthMax\",\r\n \"maxDepth\": 2\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PATH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"examples-present\",\r\n \"label\": \"Endpoints and attributes include examples\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-for-create-update\",\r\n \"label\": \"POST is used for create or update\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose create or update operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-for-remove\",\r\n \"label\": \"DELETE is used to remove resources\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose delete operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-no-request-body\",\r\n \"label\": \"GET has no request body and returns content\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"getNoRequestBody\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-empty-returns-204\",\r\n \"label\": \"GET returns 204 if response body is empty\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current contract returns content for all GET operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-200\",\r\n \"label\": \"POST returns 200 OK when updating\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST updates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-201\",\r\n \"label\": \"POST returns 201 Created with ID on create\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST creates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-returns-204\",\r\n \"label\": \"DELETE returns 204 on success\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose DELETE operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"400-errors-specific\",\r\n \"label\": \"400 errors provide specific error information\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"errorResponsesSpecific\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-400-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"api-audit-checklist\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"401-unauthorized\",\r\n \"label\": \"401 Unauthorized for wrong credentials\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current public storefront contract is intentionally unauthenticated.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-401-01\",\r\n \"REST-SEC-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"403-forbidden\",\r\n \"label\": \"403 Forbidden for unauthorized operations\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current profile is public read-only and exposes no unauthorized operations.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-403-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-contains-schemas\",\r\n \"label\": \"Spec contains request and response schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"schemasPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"restCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"pseudo-identifiers\",\r\n \"label\": \"UUIDs or pseudo-identifiers instead of DB IDs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"opaqueIdentifiers\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-07\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"no-sensitive-data-in-urls\",\r\n \"label\": \"No sensitive data in URLs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"noSensitiveDataInPaths\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-06\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"http-methods-match-resources\",\r\n \"label\": \"HTTP methods only for intended resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"methodResourceConsistency\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\",\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4,\r\n \"items\": [\r\n {\r\n \"id\": \"design-items-audited\",\r\n \"label\": \"All prototype and design items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"design\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"design-reflects-business-value\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/production-readiness-review.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-validated-on-change\",\r\n \"label\": \"Spec validated on every change\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"validationWorkflowPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\",\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"schema-and-examples-pass\",\r\n \"label\": \"Schema and examples pass validation\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPassValidation\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-contract-tested\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\",\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"api-audit-checklist\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"uses-https\",\r\n \"label\": \"Uses HTTPS or encrypted protocols\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"auth-protection\",\r\n \"label\": \"Endpoints protected by authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"token-auth\",\r\n \"label\": \"Token-based authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"csrf-protection\",\r\n \"label\": \"Protected against CSRF\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-08\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-development-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"inputs-auto-validated\",\r\n \"label\": \"Inputs auto-validated by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"contract-first-design\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\",\r\n \"test\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"outputs-auto-escaped\",\r\n \"label\": \"Outputs auto-escaped by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"JSON APIs do not typically require output escaping in the same way as HTML rendering.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"encryption-in-transit\",\r\n \"label\": \"Encryption for data in transit and storage\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"infra-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"message-integrity\",\r\n \"label\": \"Message integrity implemented\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"monitoring\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5,\r\n \"items\": [\r\n {\r\n \"id\": \"published-via-api-management\",\r\n \"label\": \"Published via API management\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"ci-cd\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"visible-in-dev-portal\",\r\n \"label\": \"Visible in developer portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-community-engagement-strategies\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"docs-auto-generated\",\r\n \"label\": \"Docs auto-generated from spec and schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\",\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"documentation\",\r\n \"ci-cd\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/publishing/README.md\",\r\n \"docs/api/audit/design-audit.read-only.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-auto-updated\",\r\n \"label\": \"Spec auto-updated to gateway and dev portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"contract-first-design\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"gateway-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"official-domain\",\r\n \"label\": \"Published under official organization domain\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6,\r\n \"items\": []\r\n }\r\n ],\r\n \"guidelines\": [\r\n {\r\n \"id\": \"REST-CONTRACT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST implement endpoints, parameters, request bodies, response bodies, and error responses as defined in the validated OpenAPI contract.\",\r\n \"relatedAuditItems\": [\r\n \"spec-contains-schemas\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CONTRACT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST keep the implementation, published OpenAPI description, gateway configuration, and developer portal documentation aligned on every change.\",\r\n \"relatedAuditItems\": [\r\n \"docs-auto-generated\",\r\n \"spec-auto-updated\",\r\n \"spec-validated-on-change\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VALIDATION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate path parameters, query parameters, headers, and JSON request bodies against the OpenAPI schema before business processing.\",\r\n \"relatedAuditItems\": [\r\n \"mandatory-fields-specified\",\r\n \"400-errors-specific\",\r\n \"inputs-auto-validated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST expose business-oriented resources and attributes rather than raw backend tables, internal service payloads, or system-specific field names.\",\r\n \"relatedAuditItems\": [\r\n \"based-on-clear-business-needs\",\r\n \"hides-raw-backend-data\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST preserve validated meanings of entities, attributes, statuses, and source-of-truth rules across all endpoints and operations.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\",\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use descriptive English names for resources and attributes.\",\r\n \"relatedAuditItems\": [\r\n \"descriptive-english-naming\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST avoid unexplained acronyms in public field and resource names.\",\r\n \"relatedAuditItems\": [\r\n \"field-names-avoid-acronyms\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use ISO date-time values with timezone information where dates are exposed.\",\r\n \"relatedAuditItems\": [\r\n \"dates-use-iso\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API SHOULD use standard codes, controlled vocabularies, and standardized value sets where applicable.\",\r\n \"relatedAuditItems\": [\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST describe the business value and feature intent of each endpoint or capability.\",\r\n \"relatedAuditItems\": [\r\n \"endpoint-descriptions-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST include examples for endpoints, request bodies, response bodies, and key attributes.\",\r\n \"relatedAuditItems\": [\r\n \"examples-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API SHOULD use consistent pagination, filtering, sorting, and response conventions across resources.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-GET-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use GET for safe read-only operations and MUST NOT define a request body for GET operations.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-POST-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use POST for resource creation and other non-idempotent operations.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-PUT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use PUT only for full resource replacement.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-DELETE-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use DELETE to remove resources.\",\r\n \"relatedAuditItems\": [\r\n \"delete-for-remove\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PATH-01\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"resource-modeling\",\r\n \"requirement\": \"The REST API SHOULD keep endpoint paths shallow and avoid more than two resource or sub-resource levels unless explicitly justified.\",\r\n \"relatedAuditItems\": [\r\n \"paths-max-two-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-200-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 200 OK for successful reads and updates that include a response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"post-returns-200\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-201-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 201 Created and the created resource identifier when a new resource is created.\",\r\n \"relatedAuditItems\": [\r\n \"create-returns-identifiers\",\r\n \"post-returns-201\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 204 No Content for successful delete operations that do not return a body.\",\r\n \"relatedAuditItems\": [\r\n \"delete-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API SHOULD return 204 No Content for successful operations that intentionally return no response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-empty-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-400-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST define 400 Bad Request responses with specific and actionable validation error information.\",\r\n \"relatedAuditItems\": [\r\n \"400-errors-specific\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-401-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 401 Unauthorized for missing or invalid credentials.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-403-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 403 Forbidden for authenticated clients lacking sufficient permission.\",\r\n \"relatedAuditItems\": [\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VERSION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"versioning\",\r\n \"requirement\": \"The REST API MUST define a versioning strategy before production release, and the strategy MUST be supportable by the API gateway.\",\r\n \"relatedAuditItems\": [\r\n \"versioning-decided\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST require authentication for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use token-based authentication or another approved modern authentication mechanism for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"token-auth\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-03\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST enforce object-level and function-level authorization on every protected operation.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\",\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST mitigate OWASP API risks including broken object level authorization, broken function level authorization, injection, and unrestricted resource consumption.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"rate-limits-enforced\",\r\n \"no-sensitive-data-in-urls\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-05\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use HTTPS or another approved encrypted protocol for all traffic.\",\r\n \"relatedAuditItems\": [\r\n \"uses-https\",\r\n \"encryption-in-transit\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-06\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST NOT expose sensitive information in URLs, query strings, logs, or unnecessary response fields.\",\r\n \"relatedAuditItems\": [\r\n \"no-sensitive-data-in-urls\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-07\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API SHOULD use UUIDs or other non-sequential public identifiers where direct database identifiers would increase exposure risk.\",\r\n \"relatedAuditItems\": [\r\n \"pseudo-identifiers\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-08\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST implement CSRF protection where relevant to the authentication model and client interaction pattern.\",\r\n \"relatedAuditItems\": [\r\n \"csrf-protection\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST define and enforce rate limits, throttling, or quotas according to capacity expectations.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST implement resilience controls such as timeouts, fallback behavior, and degradation handling according to business impact.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-OBS-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"observability\",\r\n \"requirement\": \"The REST API MUST implement logs, metrics, and monitoring needed to observe validation failures, auth failures, traffic, latency, and dependency health.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published through an API management platform.\",\r\n \"relatedAuditItems\": [\r\n \"published-via-api-management\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be accessible only through approved API gateway paths and managed entry points.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API SHOULD be visible in a developer portal with documentation generated from the contract.\",\r\n \"relatedAuditItems\": [\r\n \"visible-in-dev-portal\",\r\n \"docs-auto-generated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published under an approved organizational domain.\",\r\n \"relatedAuditItems\": [\r\n \"official-domain\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate the specification, schema, and examples on every change.\",\r\n \"relatedAuditItems\": [\r\n \"spec-validated-on-change\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST pass concept, design, security, and production-readiness checks before release.\",\r\n \"relatedAuditItems\": [\r\n \"concept-items-audited\",\r\n \"design-items-audited\"\r\n ]\r\n }\r\n ]\r\n}\r\n", "draft": false }, { "id": "api-compliance-best-practices", "slug": "resources/api-compliance-best-practices", "title": "Boas práticas de conformidade da API", "description": "Garantir que as APIs cumprem conformidade legal, regulamentar e interna através de documentação, controlos e validações automatizadas.", "category": "guideline", "icon": "edit-document-outline", "order": 104, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de conformidade da API", "Abordagem normalizada utilizando as Melhores Práticas de Conformidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Documentar as medidas de conformidade e garantir que são comunicadas às partes interessadas e aos utilizadores.", "Implementar medidas para garantir que as APIs cumprem estes requisitos, incluindo encriptação de dados, controlos de acesso e pistas de auditoria.", "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "automation-readiness-checklist", "slug": "resources/automation-readiness-checklist", "title": "Checklist de prontidão da automatização", "description": "Uma checklist para validar workflow de automatização, controlos, risco, conformidade, supervisão humana, evidências de teste, rollback, operações e prontidão para publicação.", "category": "checklist", "icon": "check-box-outline", "order": 187, "outcomes": [ "Prontidão da automatização documentada", "Lacunas de prontidão conhecidas e mitigações antes da publicação", "Evidências para qualidade, risco, conformidade, supervisão e aprovação operacional" ], "steps": [ "Reveja desenho do workflow, regras de negócio, controlos, acesso, tratamento de dados e caminhos de exceção.", "Verifique evidências de teste, procedimentos de rollback, modelo de supervisão e prontidão do suporte.", "Confirme responsabilidade, runbooks, monitorização, controlos de alteração e aprovação de publicação.", "Registe lacunas por resolver, decisões e riscos aceites antes da publicação." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "promptIds": [ "governance-specialist:facilitate-station", "governance-specialist:use-resources", "governance-specialist:next-actions" ] }, { "id": "platform-owner", "stakeholderId": "platform-owner", "title": "Responsável pela plataforma", "summary": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "stakeholder": { "id": "platform-owner", "sourceKey": "platform-owner", "sourceStakeholderId": "platform-owner", "title": "Responsável pela plataforma", "description": "Responsável pelas capacidades da plataforma, roadmap, modelo operacional e expectativas de serviço.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." }, { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." }, { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." } ], "canvases": [ { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" }, { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "capabilityBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da Capacidade" } ], "decisions": [ "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência." ], "outputs": [ "Corte APIs redundantes e reduza os custos da plataforma de nuvem", "Implementar uma governação consistente snum forte controlo do topo para a base", "Conceção para reutilização interna e escalabilidade externa", "architecture-decision", "documentation", "platform-config", "metrics", "Uma proposta de valor e um público-alvo da API simples" ], "recommendedResources": [ { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityBusinessModelCanvas", "slug": "resources/capability-business-model-canvas", "title": "Canvas do Modelo de Negócio da Capacidade", "description": "Um canvas de modelo de negócio para capacidades de integração reutilizáveis, cobrindo valor, utilizadores, propriedade, envolvimento, custos e benefícios sem assumir disponibilização por API.", "category": "canvas", "icon": "dashboard-outline", "order": 3.1, "outcomes": [ "Modelo operacional viável para a capacidade reutilizável", "Propriedade, utilizadores, canais, parceiros e necessidades de suporte clarificados", "Custos e benefícios visíveis antes do compromisso com a arquitetura" ], "steps": [ "Resuma a proposta de valor da capacidade.", "Identifique segmentos de utilizadores e canais de envolvimento.", "Defina atividades, recursos e parceiros-chave.", "Capte custos e benefícios.", "Clarifique propriedade, financiamento, suporte e expectativas de ciclo de vida.", "Valide o modelo com utilizadores, produtores e partes interessadas de governação." ], "canvasId": "capabilityBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-metrics-and-analytics", "slug": "resources/api-metrics-and-analytics", "title": "Métricas e análise de API", "description": "Um recurso para definir, recolher e analisar o desempenho da API e os dados de utilização para alinhar os KPIs técnicos com os resultados de negócio.", "category": "guideline", "icon": "edit-document-outline", "order": 119, "outcomes": [ "Melhor compreensão dos princípios de métrica e análise de API", "Abordagem normalizada utilizando métricas e análise de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação" ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-community-engagement-strategies", "slug": "resources/api-community-engagement-strategies", "title": "Estratégias de envolvimento da comunidade API", "description": "Um manual para promover a adoção de APIs, cultivando comunidades através de conteúdos, canais de apoio, ciclos de feedback e estratégias de envolvimento social.", "category": "guideline", "icon": "edit-document-outline", "order": 103, "outcomes": [ "Melhor compreensão dos princípios das estratégias de envolvimento da comunidade da API", "Abordagem normalizada utilizando as estratégias de envolvimento da comunidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Desenvolver estratégias de marketing para promover as APIs junto de públicos-alvo, incluindo redes sociais, blogues e webinars.", "Criar materiais promocionais (por exemplo, estudos de casos, histórias de sucesso) que realcem o valor e as vantagens das APIs.", "Criar materiais educativos (por exemplo, tutoriais, documentação) que expliquem as características, as vantagens e os padrões de utilização da API.", "Interagir com os utilizadores da API através de ciclos de feedback, canais de apoio e fóruns da comunidade para compreender as suas necessidades e melhorar a adoção da API.", "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "partner-integration-guidelines", "slug": "resources/partner-integration-guidelines", "title": "Diretrizes de integração de parceiros", "description": "Listas de verificação de integração e padrões de comunicação para gerir os aspectos técnicos e legais das relações com APIs de terceiros.", "category": "guideline", "icon": "edit-document-outline", "order": 164, "outcomes": [ "Melhor compreensão dos princípios das diretrizes de integração de parceiros", "Abordagem normalizada utilizando as Diretrizes de Integração de Parceiros", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Estabelecer processos de integração e orientações para colaborar com os parceiros, incluindo a integração técnica, a partilha de dados e o apoio.", "Monitorize o desempenho e a conformidade da API do parceiro para garantir a fiabilidade e o alinhamento com a sua estratégia de API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "promptIds": [ "platform-owner:facilitate-station", "platform-owner:use-resources", "platform-owner:next-actions" ] }, { "id": "process-owner", "stakeholderId": "process-owner", "title": "Responsável pelo processo", "summary": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "stakeholder": { "id": "process-owner", "sourceKey": "process-owner", "sourceStakeholderId": "process-owner", "title": "Responsável pelo processo", "description": "Responsável pelo processo de negócio a automatizar, incluindo objetivos, regras, resultados e prioridades de melhoria.", "involvement": "" }, "cycles": [ { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." }, { "id": "api-consumer-experience", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento." }, { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." }, { "id": "api-delivery", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia." }, { "id": "api-audit", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição." }, { "id": "api-publishing", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." } ], "canvases": [ { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "consumerExperienceRequirementsCanvas", "title": "Canvas de Requisitos da Experiência do Utilizador" }, { "id": "interactionCanvas", "title": "Canvas de Interação" } ], "decisions": [ "Explore o problema do cliente ou parceiro que espera resolver com as APIs. Mapeie as partes interessadas, os seus percursos e os resultados utilizando a Canvas do Percurso do Cliente.", "Definir as entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre jornadas e, eventualmente, APIs.", "Utilize o Canvas da Proposta de Valor da API para capturar as tarefas de negócios suportadas e as dores, ganhos e recursos do consumidor da API que moldam APIs novas ou reutilizáveis.", "Defina o valor - para os utilizadores e para a empresa - com a Canvas do Modelo de Negócio da API para tornar a sua estratégia de API visual, partilhável e fácil de validar com os seus consumidores de API na estação seguinte.", "Fornecer diretrizes e modelos para a criação de modelos comerciais, propostas de valor e roteiros de API.", "Muitas organizações pensam nas APIs como projetos tecnológicos e não como produtos. O resultado? Consumidores confusos, fraca adoção e esforço desperdiçado.\n\nEsta estação ajuda-o a definir o objetivo da sua API, o público-alvo e os critérios de sucesso, para que as equipas possam fornecer APIs que resolvam problemas reais." ], "outputs": [ "Uma proposta de valor e um público-alvo da API simples", "Linguagem partilhada entre o produto, a conceção e a tecnologia", "Um argumento sólido ou um caso para financiamento/aprovação", "design-artifact", "documentation", "research", "roadmap", "Identifique e dê prioridade aos seus consumidores de API" ], "recommendedResources": [ { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "process-workflow-design-guide", "slug": "resources/process-workflow-design-guide", "title": "Guia de desenho do processo e workflow", "description": "Orientação para modelar passos do processo, papéis, passagens de responsabilidade, pontos de decisão, estados, entradas, saídas e exceções que moldam um workflow de automatização.", "category": "guideline", "icon": "edit-document-outline", "order": 181, "outcomes": [ "Desenho claro do workflow de automatização", "Passos do processo e passagens de responsabilidade documentados antes da implementação", "Estados do workflow, entradas, saídas e caminhos de exceção compreendidos" ], "steps": [ "Mapeie o fluxo do processo atual e alvo, incluindo responsabilidades humanas e dos sistemas.", "Identifique gatilhos do workflow, estados, decisões, entradas de dados, saídas e critérios de conclusão.", "Documente passagens de responsabilidade entre utilizadores, sistemas, operações e papéis de suporte.", "Confirme que passos devem ser automatizados e quais exigem julgamento humano." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "decision-business-rules-guide", "slug": "resources/decision-business-rules-guide", "title": "Guia de decisões e regras de negócio", "description": "Orientação para captar regras, limiares, decisões, aprovações, verificações de elegibilidade e responsabilidade pelas regras no desenho de automatizações.", "category": "guideline", "icon": "edit-document-outline", "order": 182, "outcomes": [ "Decisões e regras de negócio explícitas", "Regras e limiares documentados com responsáveis", "Decisões da automatização rastreáveis a políticas, processos ou intenção de negócio" ], "steps": [ "Liste as decisões que a automatização deve tomar ou apoiar.", "Documente condições das regras, limiares, exceções, aprovações e pontos de escalamento.", "Identifique responsáveis pelas regras e governação de alterações para cada área de decisão." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "automation-trigger-handoff-exception-guide", "slug": "resources/automation-trigger-handoff-exception-guide", "title": "Guia de gatilhos, passagens de responsabilidade e exceções da automatização", "description": "Orientação para definir gatilhos de automatização, passagens para intervenção humana, tratamento de exceções, tentativas repetidas, ações compensatórias e caminhos de escalamento de suporte.", "category": "guideline", "icon": "edit-document-outline", "order": 183, "outcomes": [ "Gatilhos de automatização e caminhos de exceção definidos", "Passagens para intervenção humana e escalamentos de suporte estão explícitos", "Exceções, tentativas repetidas e ações compensatórias desenhadas antes da entrega" ], "steps": [ "Defina os eventos, calendários, ações de utilizadores ou estados de sistema que acionam a automatização.", "Mapeie passagens da automatização para utilizadores, operadores ou equipas de suporte.", "Documente exceções, regras de nova tentativa, comportamento de timeout e caminhos alternativos.", "Defina alertas e limiares de escalamento para resultados de automatização falhados ou ambíguos." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "automation-testing-guide", "slug": "resources/automation-testing-guide", "title": "Guia de testes de automatização", "description": "Orientação para testar workflows automatizados, decisões, integrações, exceções, comportamento de rollback, supervisão e impacto nos utilizadores antes da publicação.", "category": "guideline", "icon": "edit-document-outline", "order": 184, "outcomes": [ "Comportamento da automatização validado", "Testes de workflow, regras, exceções e integração definidos", "Confiança na publicação para caminhos automatizados e assistidos por pessoas" ], "steps": [ "Crie testes para caminhos esperados, casos-limite, exceções, tentativas repetidas e passagens de responsabilidade.", "Valide regras de negócio e resultados de decisão com dados representativos.", "Teste rollback, recuperação, observabilidade e caminhos de intervenção manual.", "Inclua utilizadores e operadores em testes de aceitação quando a automatização altera práticas de trabalho." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "automation-operational-ownership-guide", "slug": "resources/automation-operational-ownership-guide", "title": "Guia de responsabilidade operacional da automatização", "description": "Orientação para definir responsabilidade, runbooks, supervisão, suporte, monitorização, controlo de alterações e responsabilidades de melhoria contínua para automatizações.", "category": "guideline", "icon": "edit-document-outline", "order": 185, "outcomes": [ "Modelo operacional claro para a automatização", "Responsabilidades de propriedade, suporte e escalamento atribuídas", "Práticas de monitorização e alteração prontas para operação em produção" ], "steps": [ "Defina responsáveis de negócio, técnicos e operacionais pela automatização.", "Documente runbooks, caminhos de suporte, sinais de monitorização, expectativas de serviço e regras de escalamento.", "Defina controlo de alterações e práticas de revisão para atualizações de workflow, plataforma e regras." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "promptIds": [ "process-owner:facilitate-station", "process-owner:use-resources", "process-owner:next-actions" ] }, { "id": "api-product-owner", "stakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "summary": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "stakeholder": { "id": "api-product-owner", "sourceKey": "api-product-owner", "sourceStakeholderId": "api-product-owner", "title": "Responsável pelo produto API", "description": "Conduz a oportunidade API, a priorização e as decisões ao nível do produto ao longo do ciclo de vida.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." } ], "stations": [ { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." }, { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." }, { "id": "api-product-strategy", "title": "Estratégia de produtos API - Transforme APIs em produtos estratégicos", "description": "Antes de construir qualquer coisa, defina o valor da sua API, os utilizadores e os objetivos de negócio desde o primeiro dia." }, { "id": "api-consumer-experience", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento." }, { "id": "api-delivery", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia." }, { "id": "api-audit", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição." }, { "id": "api-publishing", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." } ], "canvases": [ { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "interactionCanvas", "title": "Canvas de Interação" }, { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "capabilityValuePropositionCanvas", "title": "Canvas da Proposta de Valor da Capacidade" }, { "id": "capabilityBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da Capacidade" }, { "id": "consumerExperienceRequirementsCanvas", "title": "Canvas de Requisitos da Experiência do Utilizador" }, { "id": "restCanvas", "title": "Canvas REST" }, { "id": "eventCanvas", "title": "Canvas de Eventos" }, { "id": "graphqlCanvas", "title": "Canvas GraphQL" }, { "id": "apiValuePropositionCanvas", "title": "Canvas da Proposta de Valor da API" }, { "id": "apiBusinessModelCanvas", "title": "Canvas do Modelo de Negócio da API" } ], "decisions": [ "O Canvas de Impacto no Negócio ajuda a identificar e mitigar os riscos relacionados com a disponibilidade, segurança e funcionalidade da API para apoiar decisões de arquitetura informadas.", "Mapear as localizações regulamentares, de conformidade e de rede dos fornecedores e consumidores de API para garantir a acessibilidade e a conformidade.", "O Canvas de Capacidade alinha os padrões das transacções comerciais, as tendências de consumo futuro e as soluções técnicas para garantir a escalabilidade e o desempenho da API, fornecendo dados essenciais para as decisões de escalabilidade e o planeamento da infraestrutura.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Estabelecer uma infraestrutura escalável, segura e compatível com as operações de API. Fornecer orientações sobre as boas práticas de arquitetura.", "Quando as APIs são escalonadas entre equipas, a sua plataforma deve permitir a governação e a reutilização sem bloquear a velocidade. Esta estação mostra como arquitetar APIs para longevidade, segurança e eficiência." ], "outputs": [ "Corte APIs redundantes e reduza os custos da plataforma de nuvem", "Implementar uma governação consistente snum forte controlo do topo para a base", "Conceção para reutilização interna e escalabilidade externa", "architecture-decision", "documentation", "platform-config", "metrics", "Conceção de API bem documentada e coerente" ], "recommendedResources": [ { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "contract-first-design", "slug": "resources/contract-first-design", "title": "Primeira conceção do contrato", "description": "Uma diretriz que defende abordagens API-first utilizando contratos formais (por exemplo, OpenAPI) para alinhar as partes interessadas antes do desenvolvimento.", "category": "guideline", "icon": "edit-document-outline", "order": 146, "outcomes": [ "Melhor compreensão dos princípios de conceção da primeira fase do contrato", "Abordagem normalizada utilizando a conceção orientada por contrato", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar." ], "canvasId": null, "sourcePath": "src/snippets/api-contract-example.yaml", "sourceUrl": null, "contentMarkdown": "openapi: 3.0.3\r\ninfo:\r\n title: Sample Catalog API\r\n version: 1.0.0\r\n description: |\r\n Starter example for a read-only APIOps Cycles API.\r\n This example keeps the contract audit-friendly and easy to extend.\r\nservers:\r\n - url: /v1\r\n description: Versioned API base path\r\ntags:\r\n - name: catalog\r\n description: Browse and search catalog items\r\npaths:\r\n /items:\r\n get:\r\n tags: [catalog]\r\n summary: List catalog items\r\n description: Returns a paginated list of public catalog items.\r\n operationId: listItems\r\n parameters:\r\n - $ref: \"#/components/parameters/searchTerm\"\r\n - $ref: \"#/components/parameters/categoryId\"\r\n - $ref: \"#/components/parameters/page\"\r\n - $ref: \"#/components/parameters/pageSize\"\r\n responses:\r\n \"200\":\r\n description: Item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n examples:\r\n default:\r\n value:\r\n data:\r\n - itemId: item-123\r\n slug: blue-widget\r\n name: Blue Widget\r\n status: published\r\n page:\r\n number: 1\r\n size: 20\r\n totalItems: 1\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"429\":\r\n $ref: \"#/components/responses/TooManyRequests\"\r\n /items/{itemId}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by id\r\n description: Returns a single public catalog item by opaque identifier.\r\n operationId: getItemById\r\n parameters:\r\n - $ref: \"#/components/parameters/itemId\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /items/by-slug/{slug}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by slug\r\n description: Returns a single item by public slug.\r\n operationId: getItemBySlug\r\n parameters:\r\n - $ref: \"#/components/parameters/slug\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /categories/{categoryId}/items:\r\n get:\r\n tags: [catalog]\r\n summary: List items in category\r\n description: Returns public items in a category.\r\n operationId: listItemsByCategory\r\n parameters:\r\n - $ref: \"#/components/parameters/categoryId\"\r\n responses:\r\n \"200\":\r\n description: Category item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\ncomponents:\r\n parameters:\r\n itemId:\r\n name: itemId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: item-123\r\n slug:\r\n name: slug\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9]+(?:-[a-z0-9]+)*$\"\r\n example: blue-widget\r\n categoryId:\r\n name: categoryId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: home-goods\r\n searchTerm:\r\n name: searchTerm\r\n in: query\r\n required: false\r\n schema:\r\n type: string\r\n minLength: 1\r\n example: widget\r\n page:\r\n name: page\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n default: 1\r\n pageSize:\r\n name: pageSize\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n maximum: 100\r\n default: 20\r\n responses:\r\n BadRequest:\r\n description: Validation failed\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n examples:\r\n default:\r\n value:\r\n code: BAD_REQUEST\r\n message: Invalid request\r\n NotFound:\r\n description: Resource not found\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n TooManyRequests:\r\n description: Rate limit exceeded\r\n headers:\r\n Retry-After:\r\n schema:\r\n type: integer\r\n description: Seconds until the next allowed request.\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n schemas:\r\n ItemListResponse:\r\n type: object\r\n required: [data, page]\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/ItemSummary\"\r\n page:\r\n $ref: \"#/components/schemas/Page\"\r\n ItemSummary:\r\n type: object\r\n required: [itemId, slug, name, status]\r\n properties:\r\n itemId:\r\n type: string\r\n slug:\r\n type: string\r\n name:\r\n type: string\r\n status:\r\n type: string\r\n enum: [published, hidden]\r\n ItemDetail:\r\n allOf:\r\n - $ref: \"#/components/schemas/ItemSummary\"\r\n - type: object\r\n properties:\r\n description:\r\n type: string\r\n categories:\r\n type: array\r\n items:\r\n type: string\r\n variants:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/Variant\"\r\n Variant:\r\n type: object\r\n required: [variantId, sku, price, inventory]\r\n properties:\r\n variantId:\r\n type: string\r\n sku:\r\n type: string\r\n price:\r\n $ref: \"#/components/schemas/Price\"\r\n inventory:\r\n $ref: \"#/components/schemas/Inventory\"\r\n Price:\r\n type: object\r\n required: [amount, currency]\r\n properties:\r\n amount:\r\n type: number\r\n format: decimal\r\n currency:\r\n type: string\r\n example: EUR\r\n Inventory:\r\n type: object\r\n required: [available]\r\n properties:\r\n available:\r\n type: integer\r\n minimum: 0\r\n reserved:\r\n type: integer\r\n minimum: 0\r\n source:\r\n type: string\r\n Page:\r\n type: object\r\n required: [number, size, totalItems]\r\n properties:\r\n number:\r\n type: integer\r\n size:\r\n type: integer\r\n totalItems:\r\n type: integer\r\n ErrorResponse:\r\n type: object\r\n required: [code, message]\r\n properties:\r\n code:\r\n type: string\r\n message:\r\n type: string\r\n", "draft": true }, { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityBusinessModelCanvas", "slug": "resources/capability-business-model-canvas", "title": "Canvas do Modelo de Negócio da Capacidade", "description": "Um canvas de modelo de negócio para capacidades de integração reutilizáveis, cobrindo valor, utilizadores, propriedade, envolvimento, custos e benefícios sem assumir disponibilização por API.", "category": "canvas", "icon": "dashboard-outline", "order": 3.1, "outcomes": [ "Modelo operacional viável para a capacidade reutilizável", "Propriedade, utilizadores, canais, parceiros e necessidades de suporte clarificados", "Custos e benefícios visíveis antes do compromisso com a arquitetura" ], "steps": [ "Resuma a proposta de valor da capacidade.", "Identifique segmentos de utilizadores e canais de envolvimento.", "Defina atividades, recursos e parceiros-chave.", "Capte custos e benefícios.", "Clarifique propriedade, financiamento, suporte e expectativas de ciclo de vida.", "Valide o modelo com utilizadores, produtores e partes interessadas de governação." ], "canvasId": "capabilityBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false } ], "promptIds": [ "api-product-owner:facilitate-station", "api-product-owner:use-resources", "api-product-owner:next-actions" ] }, { "id": "api-devrel-specialist", "stakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "summary": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "stakeholder": { "id": "api-devrel-specialist", "sourceKey": "api-devrel-specialist", "sourceStakeholderId": "api-devrel-specialist", "title": "Responsável por documentação e DevRel", "description": "Responsável por conteúdos de onboarding, comunicação com programadores e qualidade da documentação para utilizadores da API.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." }, { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-consumer-experience", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento." }, { "id": "api-publishing", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." }, { "id": "api-design", "title": "Conceção da API - Conceber APIs que proporcionem valor", "description": "Criar conceções de API que sejam consistentes, reutilizáveis e baseados na intenção de negócios e em padrões compartilhados." } ], "canvases": [ { "id": "consumerExperienceRequirementsCanvas", "title": "Canvas de Requisitos da Experiência do Utilizador" }, { "id": "domainCanvas", "title": "Canvas de Domínio" }, { "id": "interactionCanvas", "title": "Canvas de Interação" }, { "id": "apiValuePropositionCanvas", "title": "Canvas da Proposta de Valor da API" }, { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" }, { "id": "restCanvas", "title": "Canvas REST" }, { "id": "eventCanvas", "title": "Canvas de Eventos" }, { "id": "graphqlCanvas", "title": "Canvas GraphQL" } ], "decisions": [ "Analise o Canvas da Proposta de Valor da API existente sob a perspectiva do consumidor da API. Mantenha as tarefas de negócios suportadas estáveis ​​e enriqueça os recursos que aliviam problemas e possibilitam ganhos com as preocupações do consumidor da API, para que elas possam orientar as decisões de conceção futuras.", "Utilize o Canvas do Percurso do Cliente para a jornada do consumidor da API, desde a descoberta e avaliação até a integração, resolução de problemas e uso contínuo.", "Utilize a jornada resultante para melhorar a integração, a documentação, o suporte e os ciclos de feedback para o consumidor da API.", "Fornecer diretrizes, ferramentas e mecanismos de feedback para compreender, analisar e melhorar a experiência interna e externa dos programadores e parceiros.", "As APIs excelentes não funcionam apenas - elas são intuitivas. Quer o consumidor seja um programador interno, um parceiro externo ou um agente de IA, a sua experiência determina a adoção.\n\nSnum plano de experiência claro:\n- Grandes APIs ficam sem uso\n- As equipas perdem tempo a tentar adivinhar como utilizar a sua API\n- Os ciclos de feedback estão quebrados ou ausentes.\n\nEsta estação ajuda-o a ver a sua API através dos olhos dos seus consumidores.", "Publicar APIs nos gateways e ambientes adequados para apoiar a reutilização por vários consumidores de API." ], "outputs": [ "Identifique e dê prioridade aos seus consumidores de API", "Definir o percurso da experiência API", "Planeamento da integração, documentação e feedback", "Melhorar a adoção através de empatia genuína + Experiência do Programador (DX)", "design-artifact", "documentation", "consumer-feedback", "APIs publicadas no ambiente correto (privado, parceiro, público)" ], "recommendedResources": [ { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "service-agreement-template", "slug": "resources/service-agreement-template", "title": "Modelo de contrato de serviço", "description": "Um formato de acordo personalizável que define expectativas, SLAs, responsabilidades e termos de acesso para o consumo de API.", "category": "guideline", "icon": "edit-document-outline", "order": 172, "outcomes": [ "Melhor compreensão dos princípios do modelo de contrato de prestação de serviços", "Abordagem normalizada utilizando o modelo de contrato de serviços", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Defina acordos de serviço que descrevam as expectativas, os níveis de serviço e as responsabilidades de cada API.", "Utilize formatos normalizados para criar contratos de serviço legíveis por máquina que sejam fáceis de partilhar e validar.", "Assegurar que os acordos de serviço são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-metrics-and-analytics", "slug": "resources/api-metrics-and-analytics", "title": "Métricas e análise de API", "description": "Um recurso para definir, recolher e analisar o desempenho da API e os dados de utilização para alinhar os KPIs técnicos com os resultados de negócio.", "category": "guideline", "icon": "edit-document-outline", "order": 119, "outcomes": [ "Melhor compreensão dos princípios de métrica e análise de API", "Abordagem normalizada utilizando métricas e análise de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação" ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-community-engagement-strategies", "slug": "resources/api-community-engagement-strategies", "title": "Estratégias de envolvimento da comunidade API", "description": "Um manual para promover a adoção de APIs, cultivando comunidades através de conteúdos, canais de apoio, ciclos de feedback e estratégias de envolvimento social.", "category": "guideline", "icon": "edit-document-outline", "order": 103, "outcomes": [ "Melhor compreensão dos princípios das estratégias de envolvimento da comunidade da API", "Abordagem normalizada utilizando as estratégias de envolvimento da comunidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Desenvolver estratégias de marketing para promover as APIs junto de públicos-alvo, incluindo redes sociais, blogues e webinars.", "Criar materiais promocionais (por exemplo, estudos de casos, histórias de sucesso) que realcem o valor e as vantagens das APIs.", "Criar materiais educativos (por exemplo, tutoriais, documentação) que expliquem as características, as vantagens e os padrões de utilização da API.", "Interagir com os utilizadores da API através de ciclos de feedback, canais de apoio e fóruns da comunidade para compreender as suas necessidades e melhorar a adoção da API.", "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "contract-first-design", "slug": "resources/contract-first-design", "title": "Primeira conceção do contrato", "description": "Uma diretriz que defende abordagens API-first utilizando contratos formais (por exemplo, OpenAPI) para alinhar as partes interessadas antes do desenvolvimento.", "category": "guideline", "icon": "edit-document-outline", "order": 146, "outcomes": [ "Melhor compreensão dos princípios de conceção da primeira fase do contrato", "Abordagem normalizada utilizando a conceção orientada por contrato", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar." ], "canvasId": null, "sourcePath": "src/snippets/api-contract-example.yaml", "sourceUrl": null, "contentMarkdown": "openapi: 3.0.3\r\ninfo:\r\n title: Sample Catalog API\r\n version: 1.0.0\r\n description: |\r\n Starter example for a read-only APIOps Cycles API.\r\n This example keeps the contract audit-friendly and easy to extend.\r\nservers:\r\n - url: /v1\r\n description: Versioned API base path\r\ntags:\r\n - name: catalog\r\n description: Browse and search catalog items\r\npaths:\r\n /items:\r\n get:\r\n tags: [catalog]\r\n summary: List catalog items\r\n description: Returns a paginated list of public catalog items.\r\n operationId: listItems\r\n parameters:\r\n - $ref: \"#/components/parameters/searchTerm\"\r\n - $ref: \"#/components/parameters/categoryId\"\r\n - $ref: \"#/components/parameters/page\"\r\n - $ref: \"#/components/parameters/pageSize\"\r\n responses:\r\n \"200\":\r\n description: Item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n examples:\r\n default:\r\n value:\r\n data:\r\n - itemId: item-123\r\n slug: blue-widget\r\n name: Blue Widget\r\n status: published\r\n page:\r\n number: 1\r\n size: 20\r\n totalItems: 1\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"429\":\r\n $ref: \"#/components/responses/TooManyRequests\"\r\n /items/{itemId}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by id\r\n description: Returns a single public catalog item by opaque identifier.\r\n operationId: getItemById\r\n parameters:\r\n - $ref: \"#/components/parameters/itemId\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /items/by-slug/{slug}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by slug\r\n description: Returns a single item by public slug.\r\n operationId: getItemBySlug\r\n parameters:\r\n - $ref: \"#/components/parameters/slug\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /categories/{categoryId}/items:\r\n get:\r\n tags: [catalog]\r\n summary: List items in category\r\n description: Returns public items in a category.\r\n operationId: listItemsByCategory\r\n parameters:\r\n - $ref: \"#/components/parameters/categoryId\"\r\n responses:\r\n \"200\":\r\n description: Category item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\ncomponents:\r\n parameters:\r\n itemId:\r\n name: itemId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: item-123\r\n slug:\r\n name: slug\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9]+(?:-[a-z0-9]+)*$\"\r\n example: blue-widget\r\n categoryId:\r\n name: categoryId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: home-goods\r\n searchTerm:\r\n name: searchTerm\r\n in: query\r\n required: false\r\n schema:\r\n type: string\r\n minLength: 1\r\n example: widget\r\n page:\r\n name: page\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n default: 1\r\n pageSize:\r\n name: pageSize\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n maximum: 100\r\n default: 20\r\n responses:\r\n BadRequest:\r\n description: Validation failed\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n examples:\r\n default:\r\n value:\r\n code: BAD_REQUEST\r\n message: Invalid request\r\n NotFound:\r\n description: Resource not found\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n TooManyRequests:\r\n description: Rate limit exceeded\r\n headers:\r\n Retry-After:\r\n schema:\r\n type: integer\r\n description: Seconds until the next allowed request.\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n schemas:\r\n ItemListResponse:\r\n type: object\r\n required: [data, page]\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/ItemSummary\"\r\n page:\r\n $ref: \"#/components/schemas/Page\"\r\n ItemSummary:\r\n type: object\r\n required: [itemId, slug, name, status]\r\n properties:\r\n itemId:\r\n type: string\r\n slug:\r\n type: string\r\n name:\r\n type: string\r\n status:\r\n type: string\r\n enum: [published, hidden]\r\n ItemDetail:\r\n allOf:\r\n - $ref: \"#/components/schemas/ItemSummary\"\r\n - type: object\r\n properties:\r\n description:\r\n type: string\r\n categories:\r\n type: array\r\n items:\r\n type: string\r\n variants:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/Variant\"\r\n Variant:\r\n type: object\r\n required: [variantId, sku, price, inventory]\r\n properties:\r\n variantId:\r\n type: string\r\n sku:\r\n type: string\r\n price:\r\n $ref: \"#/components/schemas/Price\"\r\n inventory:\r\n $ref: \"#/components/schemas/Inventory\"\r\n Price:\r\n type: object\r\n required: [amount, currency]\r\n properties:\r\n amount:\r\n type: number\r\n format: decimal\r\n currency:\r\n type: string\r\n example: EUR\r\n Inventory:\r\n type: object\r\n required: [available]\r\n properties:\r\n available:\r\n type: integer\r\n minimum: 0\r\n reserved:\r\n type: integer\r\n minimum: 0\r\n source:\r\n type: string\r\n Page:\r\n type: object\r\n required: [number, size, totalItems]\r\n properties:\r\n number:\r\n type: integer\r\n size:\r\n type: integer\r\n totalItems:\r\n type: integer\r\n ErrorResponse:\r\n type: object\r\n required: [code, message]\r\n properties:\r\n code:\r\n type: string\r\n message:\r\n type: string\r\n", "draft": true }, { "id": "apiValuePropositionCanvas", "slug": "resources/api-value-proposition-canvas", "title": "Canvas da Proposta de Valor da API", "description": "Alinhar as funcionalidades da API com as necessidades dos utilizadores, mapeando tarefas, problemas e ganhos para os produtos da API.", "category": "canvas", "icon": "dashboard-outline", "order": 2, "outcomes": [ "Desenvolvimento de funcionalidades específicas", "Alinhamento com as necessidades dos utilizadores", "Melhoria da satisfação do utilizador da API" ], "steps": [ "Listar as tarefas do percurso do utilizador", "Identificar as características que proporcionam os ganhos esperados", "Definir características para enfrentar os desafios", "Mapear características para produtos API" ], "canvasId": "apiValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false } ], "promptIds": [ "api-devrel-specialist:facilitate-station", "api-devrel-specialist:use-resources", "api-devrel-specialist:next-actions" ] }, { "id": "operations-specialist", "stakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "summary": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "stakeholder": { "id": "operations-specialist", "sourceKey": "operations-specialist", "sourceStakeholderId": "operations-specialist", "title": "Responsável por suporte e operações", "description": "Representa o suporte em execução, tratamento de incidentes, observabilidade e prontidão operacional da capacidade, API ou automatização.", "involvement": "" }, "cycles": [ { "id": "capability-productization-cycle", "title": "Ciclo de Produto de Capacidades", "description": "Um ciclo para transformar capacidades de negócio em capacidades digitais reutilizáveis antes de selecionar o estilo de implementação." }, { "id": "api-productization-cycle", "title": "Ciclo de Produto de API", "description": "A jornada APIOps Cycles focada em API para transformar APIs em produto, concebê-las, entregá-las, publicá-las e melhorá-las." }, { "id": "integration-productization-cycle", "title": "Ciclo de Produto de Integração", "description": "Um ciclo para transformar capacidades de integracao reutilizaveis em produto antes de selecionar o estilo de implementacao." }, { "id": "automation-cycle", "title": "Ciclo de Automação", "description": "Um ciclo para identificar, conceber, entregar, capacitar e melhorar oportunidades de automação." } ], "stations": [ { "id": "api-consumer-experience", "title": "Experiência do consumidor da API - Conceção para os utilizadores reais da sua API", "description": "Certifique-se de que a sua API é detetável, compreensível e utilizável - antes e depois do lançamento." }, { "id": "api-delivery", "title": "Entrega da API - Fornecer APIs seguras e fiáveis", "description": "Criar, testar e lançar APIs usando pipelines de entrega modernos e boas práticas de engenharia." }, { "id": "api-audit", "title": "Auditoria de API - Auditoria de APIs para conformidade e qualidade", "description": "Valide se as APIs satisfazemos padrões de negócio, conceção e operacionais antes da publicação e exposição." }, { "id": "api-publishing", "title": "Publicação de API - Publique APIs com confiança", "description": "Exponha as APIs de forma segura e clara ao público certo com a documentação e os processos corretos." }, { "id": "monitoring-and-improving", "title": "Monitorização e melhoria - para valor API", "description": "Utilizar métricas e feedback para acompanhar o desempenho da API e promover a melhoria contínua." }, { "id": "api-platform-architecture", "title": "Arquitetura da plataforma API - Arquitetar APIs para escalabilidade e reutilização", "description": "Garanta a escalabilidade, a reutilização e a governação da sua API e dos componentes da plataforma." } ], "canvases": [ { "id": "consumerExperienceRequirementsCanvas", "title": "Canvas de Requisitos da Experiência do Utilizador" }, { "id": "businessImpactCanvas", "title": "Canvas de Impacto no Negócio" }, { "id": "locationsCanvas", "title": "Canvas de Localizações" }, { "id": "capacityCanvas", "title": "Canvas de Capacidade" }, { "id": "apiValuePropositionCanvas", "title": "Canvas da Proposta de Valor da API" }, { "id": "customerJourneyCanvas", "title": "Canvas do Percurso do Cliente" } ], "decisions": [ "Analise o Canvas da Proposta de Valor da API existente sob a perspectiva do consumidor da API. Mantenha as tarefas de negócios suportadas estáveis ​​e enriqueça os recursos que aliviam problemas e possibilitam ganhos com as preocupações do consumidor da API, para que elas possam orientar as decisões de conceção futuras.", "Utilize o Canvas do Percurso do Cliente para a jornada do consumidor da API, desde a descoberta e avaliação até a integração, resolução de problemas e uso contínuo.", "Utilize a jornada resultante para melhorar a integração, a documentação, o suporte e os ciclos de feedback para o consumidor da API.", "Fornecer diretrizes, ferramentas e mecanismos de feedback para compreender, analisar e melhorar a experiência interna e externa dos programadores e parceiros.", "As APIs excelentes não funcionam apenas - elas são intuitivas. Quer o consumidor seja um programador interno, um parceiro externo ou um agente de IA, a sua experiência determina a adoção.\n\nSnum plano de experiência claro:\n- Grandes APIs ficam sem uso\n- As equipas perdem tempo a tentar adivinhar como utilizar a sua API\n- Os ciclos de feedback estão quebrados ou ausentes.\n\nEsta estação ajuda-o a ver a sua API através dos olhos dos seus consumidores.", "Utilize as Melhores Práticas de Desenvolvimento de API como orientação para implementar o contrato validado com frameworks e bibliotecas estabelecidos, garantindo que o resultado seja reutilizável e sustentável." ], "outputs": [ "Identifique e dê prioridade aos seus consumidores de API", "Definir o percurso da experiência API", "Planeamento da integração, documentação e feedback", "Melhorar a adoção através de empatia genuína + Experiência do Programador (DX)", "design-artifact", "documentation", "consumer-feedback", "APIs implementadas utilizando estruturas e padrões testados" ], "recommendedResources": [ { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-development-best-practices", "slug": "resources/api-development-best-practices", "title": "Boas práticas de desenvolvimento de API", "description": "Orientações de implementação para transformar um contrato de interface da API validado numa base de código de API consistente e sustentável, utilizando bibliotecas padrão, padrões reutilizáveis e fluxos de trabalho de desenvolvimento alinhados.", "category": "guideline", "icon": "edit-document-outline", "order": 112, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de desenvolvimento de API", "Abordagem normalizada utilizando as boas práticas de desenvolvimento de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplique essas práticas ao contrato de interface da API validado e ao plano de implementação antes do início da codificação.", "Utilize frameworks, bibliotecas e padrões de codificação estabelecidos para implementar o contrato de forma consistente e sustentável." ], "canvasId": null, "sourcePath": "src/snippets/pt/api-design-principles-guidance.md", "sourceUrl": null, "contentMarkdown": "## Como iniciar o trabalho de entrega da API com base nas fases anteriores (“etapas”)\r\nUtilize estas orientações no início da `API Delivery` (entrega da API), após a revisão e aceitação do contrato da API (por exemplo, OpenAPI) e dos principais resultados das etapas anteriores.\r\nO objetivo não é desenvolver a implementação de forma isolada. O objetivo é transformar os resultados acordados nas etapas anteriores em uma estrutura de código concreta, regras de validação, comportamento em tempo de execução e decisões relativas à entrega do produto API.\r\n\r\n---\r\n\r\n### 1. Comece a partir do contrato validado\r\n- Trate o contrato de API validado como o principal ponto de referência para as decisões de implementação.\r\n- Mantenha o contrato e a implementação alinhados ao longo de toda a entrega do produto API.\r\n- Use o contrato para orientar a validação de solicitações, o mapeamento de respostas, a documentação e os testes.\r\n\r\n---\r\n\r\n### 2. Use os resultados do domínio para preservar o significado comercial\r\n- Use os resultados do `Domain Canvas` para orientar a nomenclatura, como a implementação é dividida em responsabilidades comerciais claras e como diferentes sistemas de back-end são conectados sem expor suas diferenças.\r\n- Preserve os significados validados de entidades, atributos, status e regras de fonte de verdade.\r\n- Evite vazar modelos específicos do back-end ou inconsistências para a API pública.\r\n\r\n---\r\n\r\n### 3. Use os resultados da jornada para preservar fluxos críticos\r\n- Use os resultados do `Customer Journey Canvas` para identificar quais fluxos de usuários são mais importantes para serem atendidos primeiro.\r\n- Use os resultados da `API Consumer Experience` para manter a API compreensível, previsível e fácil de integrar.\r\n- Deixe que as prioridades de jornada acordadas decidam quais caminhos de implementação precisam da maior confiabilidade, menor latência, erros mais claros e maior foco operacional.\r\n\r\n---\r\n\r\n### 4. Use os resultados da Proposta de Valor para preservar o valor para o consumidor\r\n- Use os resultados do `API Value Proposition Canvas` para manter a implementação focada nas dores, ganhos e recursos da API acordados.\r\n- Preserve os significados dos campos, o comportamento e as promessas que tornaram a API valiosa nas etapas anteriores.\r\n- Garanta que o tratamento de erros, a atualização e a nomenclatura apoiem tanto a experiência do desenvolvedor pretendida quanto o caso de uso de negócios.\r\n\r\n---\r\n\r\n### 5. Use os resultados da arquitetura para moldar as decisões de tempo de execução\r\n- Use os resultados do `Business Impact Canvas` para orientar as decisões sobre resiliência, tempo limite, fallback e degradação.\r\n- Use os resultados do `Locations Canvas` para orientar os limites de rede, limites de confiança, caminhos de acesso e restrições de implantação.\r\n- Use os resultados do `Capacity Canvas` para orientar limites de taxa, cache, escalonamento e comportamento em picos de carga.\r\n- Use as orientações do `API Metrics And Analytics` para decidir o que deve ser observado desde a primeira implementação em diante.\r\n\r\n---\r\n\r\n### 6. Use os resultados do projeto de interação e protocolo para moldar a estrutura do código\r\n- Use os resultados do `Interaction Canvas` para evitar implementar estilos de interação não suportados prematuramente.\r\n- Use os resultados do projeto `REST`, `Event` ou `GraphQL` para moldar o comportamento de solicitação, resposta e validação específico do protocolo.\r\n- Reflete o estilo de interação selecionado claramente na estrutura do código, nas responsabilidades e na estratégia de testes.\r\n\r\n---\r\n\r\n### 7. Usa os resultados da auditoria para melhorar a entrega antes que a codificação avance demais\r\n- Usa as conclusões da auditoria para remover ambiguidades antes que a implementação se espalhe pela base de código.\r\n- Corrige regras de solicitação pouco claras, validações ausentes, contratos de erro fracos e lacunas operacionais logo no início.\r\n- Trate a auditoria como um ciclo de melhoria de projeto antes da produção, não apenas como uma etapa de decisão final.\r\n\r\n---\r\n\r\n### 8. Aplique as orientações e, em seguida, resuma\r\n- Aplique estas orientações à API atual e ao plano de implementação.\r\n- Resuma as implicações para a estrutura do código, validação de solicitações, integração de fontes, segurança, monitoramento e alertas, e testes.\r\n- Não crie um artefato de entrega separado, a menos que a equipe ou o usuário precise especificamente de um.\r\n", "draft": true }, { "id": "api-testing-best-practices", "slug": "resources/api-testing-best-practices", "title": "Boas práticas de teste de API", "description": "Diretrizes para a implementação de testes automatizados funcionais, de desempenho e de segurança ao longo do ciclo de vida da API.", "category": "guideline", "icon": "edit-document-outline", "order": 133, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de teste de API", "Abordagem normalizada utilizando as boas práticas de teste de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Integrar testes funcionais e não funcionais no pipeline CI/CD para garantir que as APIs cumprems normas de qualidade.", "Utilizar ferramentas de teste automatizadas para validar a funcionalidade, a segurança e o desempenho da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "apiops-CI-CD-for-apis", "slug": "resources/apiops-CI-CD-for-apis", "title": "APIOps CI/CD para APIs", "description": "Orientação de disponibilização que integra tarefas do ciclo de vida da API - design, teste, governação - em pipelines de integração e entrega contínuas.", "category": "guideline", "icon": "edit-document-outline", "order": 140, "outcomes": [ "Melhor compreensão dos princípios de CI/CD para APIs", "Abordagem normalizada utilizando CI/CD para APIs", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilizar pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-audit-checklist", "slug": "resources/api-audit-checklist", "title": "Lista de verificação de auditoria da API", "description": "Uma lista de verificação baseada no ciclo de vida para verificar a prontidão da API em design, entrega, publicação e conformidade utilizando critérios de auditoria e evidências definidos.", "category": "checklist", "icon": "check-box-outline", "order": 13, "outcomes": [ "Melhor compreensão dos princípios da lista de controlo de auditoria da API", "Abordagem normalizada utilizando a lista de verificação de auditoria da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilize a lista de verificação de auditoria da API para garantir que a conceção da API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Realize auditorias para avaliar a cobertura do ciclo de vida e verificar se a API satisfaz os padrões de negócio, conceção e operacionais.", "Certifique-se de que a documentação, os modelos de segurança, a configuração do gateway e os requisitos legais estejam claramente definidos, validados e comprovados por evidências." ], "canvasId": null, "sourcePath": "src/snippets/api-audit-checklist.json", "sourceUrl": null, "contentMarkdown": "{\r\n \"profiles\": {\r\n \"read-only\": {\r\n \"description\": \"API profile that is read-only and does not allow create, update, or delete operations.\"\r\n },\r\n \"full-crud\": {\r\n \"description\": \"General API profile that allows create, update, and delete operations.\"\r\n }\r\n },\r\n \"lifecycleStages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6\r\n }\r\n ],\r\n \"stages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1,\r\n \"items\": [\r\n {\r\n \"id\": \"based-on-clear-business-needs\",\r\n \"label\": \"API is based on clear business needs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiBusinessModelCanvas\",\r\n \"apiValuePropositionCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"design-artifact\",\r\n \"documentation\",\r\n \"research\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\",\r\n \"specs/canvases/api-product-strategy/apiBusinessModelCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"concept-items-audited\",\r\n \"label\": \"All concept checklist items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"strategy\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\",\r\n \"api-opportunity-documented\",\r\n \"api-reusability\",\r\n \"value-prop-validated\",\r\n \"consumer-segments-identified\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/concept-review-report.json\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2,\r\n \"items\": [\r\n {\r\n \"id\": \"versioning-decided\",\r\n \"label\": \"Versioning strategy decided and supported by gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VERSION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-versioning-best-practices\",\r\n \"apiops-CI-CD-for-apis\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"ci-cd\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"only-via-gateway\",\r\n \"label\": \"Only accessible via API gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-02\",\r\n \"REST-CAPACITY-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"businessImpactCanvas\",\r\n \"locationsCanvas\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"infra-config\",\r\n \"security-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"rate-limits-enforced\",\r\n \"label\": \"Rate limits are enforced\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CAPACITY-01\",\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"capacityCanvas\",\r\n \"api-security-best-practices\",\r\n \"scalable-infrastructure-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"runtime\",\r\n \"monitoring\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-platform-architecture/capacityCanvas.empty.json\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3,\r\n \"items\": [\r\n {\r\n \"id\": \"endpoint-descriptions-present\",\r\n \"label\": \"Endpoints have business value and feature descriptions\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"operationDescriptions\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\",\r\n \"api-opportunity-documented\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiValuePropositionCanvas\",\r\n \"customerJourneyCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"hides-raw-backend-data\",\r\n \"label\": \"API hides raw backend data and is designed for shared use\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"interactionCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/domainCanvas.empty.json\",\r\n \"specs/canvases/api-design/interactionCanvas.empty.json\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"design-consistent\",\r\n \"label\": \"API design is consistent with other APIs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-02\",\r\n \"REST-CX-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-design/restCanvas.empty.json\",\r\n \"docs/api/design/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"descriptive-english-naming\",\r\n \"label\": \"Data and attribute naming uses descriptive English\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"fieldNamesDescriptive\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"mandatory-fields-specified\",\r\n \"label\": \"Mandatory fields are specified\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"requiredFieldsPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"dates-use-iso\",\r\n \"label\": \"Dates use ISO format with timezone\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"dateFormatTimezone\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"general-data-uses-standard-values\",\r\n \"label\": \"General data uses standard values\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"standardizedEnumsOrPatterns\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"field-names-avoid-acronyms\",\r\n \"label\": \"Field names avoid acronyms and use full words\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"avoidAcronyms\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"create-returns-identifiers\",\r\n \"label\": \"Creating new resources returns identifiers\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is read-only and does not create resources.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"paths-max-two-resources\",\r\n \"label\": \"Endpoint paths contain max two resources or sub-resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"pathDepthMax\",\r\n \"maxDepth\": 2\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PATH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"examples-present\",\r\n \"label\": \"Endpoints and attributes include examples\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-for-create-update\",\r\n \"label\": \"POST is used for create or update\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose create or update operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-for-remove\",\r\n \"label\": \"DELETE is used to remove resources\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose delete operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-no-request-body\",\r\n \"label\": \"GET has no request body and returns content\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"getNoRequestBody\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-empty-returns-204\",\r\n \"label\": \"GET returns 204 if response body is empty\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current contract returns content for all GET operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-200\",\r\n \"label\": \"POST returns 200 OK when updating\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST updates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-201\",\r\n \"label\": \"POST returns 201 Created with ID on create\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST creates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-returns-204\",\r\n \"label\": \"DELETE returns 204 on success\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose DELETE operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"400-errors-specific\",\r\n \"label\": \"400 errors provide specific error information\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"errorResponsesSpecific\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-400-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"api-audit-checklist\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"401-unauthorized\",\r\n \"label\": \"401 Unauthorized for wrong credentials\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current public storefront contract is intentionally unauthenticated.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-401-01\",\r\n \"REST-SEC-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"403-forbidden\",\r\n \"label\": \"403 Forbidden for unauthorized operations\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current profile is public read-only and exposes no unauthorized operations.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-403-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-contains-schemas\",\r\n \"label\": \"Spec contains request and response schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"schemasPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"restCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"pseudo-identifiers\",\r\n \"label\": \"UUIDs or pseudo-identifiers instead of DB IDs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"opaqueIdentifiers\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-07\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"no-sensitive-data-in-urls\",\r\n \"label\": \"No sensitive data in URLs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"noSensitiveDataInPaths\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-06\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"http-methods-match-resources\",\r\n \"label\": \"HTTP methods only for intended resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"methodResourceConsistency\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\",\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4,\r\n \"items\": [\r\n {\r\n \"id\": \"design-items-audited\",\r\n \"label\": \"All prototype and design items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"design\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"design-reflects-business-value\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/production-readiness-review.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-validated-on-change\",\r\n \"label\": \"Spec validated on every change\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"validationWorkflowPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\",\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"schema-and-examples-pass\",\r\n \"label\": \"Schema and examples pass validation\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPassValidation\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-contract-tested\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\",\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"api-audit-checklist\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"uses-https\",\r\n \"label\": \"Uses HTTPS or encrypted protocols\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"auth-protection\",\r\n \"label\": \"Endpoints protected by authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"token-auth\",\r\n \"label\": \"Token-based authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"csrf-protection\",\r\n \"label\": \"Protected against CSRF\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-08\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-development-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"inputs-auto-validated\",\r\n \"label\": \"Inputs auto-validated by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"contract-first-design\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\",\r\n \"test\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"outputs-auto-escaped\",\r\n \"label\": \"Outputs auto-escaped by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"JSON APIs do not typically require output escaping in the same way as HTML rendering.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"encryption-in-transit\",\r\n \"label\": \"Encryption for data in transit and storage\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"infra-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"message-integrity\",\r\n \"label\": \"Message integrity implemented\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"monitoring\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5,\r\n \"items\": [\r\n {\r\n \"id\": \"published-via-api-management\",\r\n \"label\": \"Published via API management\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"ci-cd\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"visible-in-dev-portal\",\r\n \"label\": \"Visible in developer portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-community-engagement-strategies\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"docs-auto-generated\",\r\n \"label\": \"Docs auto-generated from spec and schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\",\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"documentation\",\r\n \"ci-cd\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/publishing/README.md\",\r\n \"docs/api/audit/design-audit.read-only.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-auto-updated\",\r\n \"label\": \"Spec auto-updated to gateway and dev portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"contract-first-design\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"gateway-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"official-domain\",\r\n \"label\": \"Published under official organization domain\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6,\r\n \"items\": []\r\n }\r\n ],\r\n \"guidelines\": [\r\n {\r\n \"id\": \"REST-CONTRACT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST implement endpoints, parameters, request bodies, response bodies, and error responses as defined in the validated OpenAPI contract.\",\r\n \"relatedAuditItems\": [\r\n \"spec-contains-schemas\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CONTRACT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST keep the implementation, published OpenAPI description, gateway configuration, and developer portal documentation aligned on every change.\",\r\n \"relatedAuditItems\": [\r\n \"docs-auto-generated\",\r\n \"spec-auto-updated\",\r\n \"spec-validated-on-change\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VALIDATION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate path parameters, query parameters, headers, and JSON request bodies against the OpenAPI schema before business processing.\",\r\n \"relatedAuditItems\": [\r\n \"mandatory-fields-specified\",\r\n \"400-errors-specific\",\r\n \"inputs-auto-validated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST expose business-oriented resources and attributes rather than raw backend tables, internal service payloads, or system-specific field names.\",\r\n \"relatedAuditItems\": [\r\n \"based-on-clear-business-needs\",\r\n \"hides-raw-backend-data\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST preserve validated meanings of entities, attributes, statuses, and source-of-truth rules across all endpoints and operations.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\",\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use descriptive English names for resources and attributes.\",\r\n \"relatedAuditItems\": [\r\n \"descriptive-english-naming\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST avoid unexplained acronyms in public field and resource names.\",\r\n \"relatedAuditItems\": [\r\n \"field-names-avoid-acronyms\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use ISO date-time values with timezone information where dates are exposed.\",\r\n \"relatedAuditItems\": [\r\n \"dates-use-iso\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API SHOULD use standard codes, controlled vocabularies, and standardized value sets where applicable.\",\r\n \"relatedAuditItems\": [\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST describe the business value and feature intent of each endpoint or capability.\",\r\n \"relatedAuditItems\": [\r\n \"endpoint-descriptions-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST include examples for endpoints, request bodies, response bodies, and key attributes.\",\r\n \"relatedAuditItems\": [\r\n \"examples-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API SHOULD use consistent pagination, filtering, sorting, and response conventions across resources.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-GET-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use GET for safe read-only operations and MUST NOT define a request body for GET operations.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-POST-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use POST for resource creation and other non-idempotent operations.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-PUT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use PUT only for full resource replacement.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-DELETE-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use DELETE to remove resources.\",\r\n \"relatedAuditItems\": [\r\n \"delete-for-remove\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PATH-01\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"resource-modeling\",\r\n \"requirement\": \"The REST API SHOULD keep endpoint paths shallow and avoid more than two resource or sub-resource levels unless explicitly justified.\",\r\n \"relatedAuditItems\": [\r\n \"paths-max-two-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-200-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 200 OK for successful reads and updates that include a response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"post-returns-200\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-201-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 201 Created and the created resource identifier when a new resource is created.\",\r\n \"relatedAuditItems\": [\r\n \"create-returns-identifiers\",\r\n \"post-returns-201\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 204 No Content for successful delete operations that do not return a body.\",\r\n \"relatedAuditItems\": [\r\n \"delete-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API SHOULD return 204 No Content for successful operations that intentionally return no response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-empty-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-400-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST define 400 Bad Request responses with specific and actionable validation error information.\",\r\n \"relatedAuditItems\": [\r\n \"400-errors-specific\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-401-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 401 Unauthorized for missing or invalid credentials.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-403-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 403 Forbidden for authenticated clients lacking sufficient permission.\",\r\n \"relatedAuditItems\": [\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VERSION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"versioning\",\r\n \"requirement\": \"The REST API MUST define a versioning strategy before production release, and the strategy MUST be supportable by the API gateway.\",\r\n \"relatedAuditItems\": [\r\n \"versioning-decided\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST require authentication for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use token-based authentication or another approved modern authentication mechanism for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"token-auth\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-03\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST enforce object-level and function-level authorization on every protected operation.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\",\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST mitigate OWASP API risks including broken object level authorization, broken function level authorization, injection, and unrestricted resource consumption.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"rate-limits-enforced\",\r\n \"no-sensitive-data-in-urls\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-05\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use HTTPS or another approved encrypted protocol for all traffic.\",\r\n \"relatedAuditItems\": [\r\n \"uses-https\",\r\n \"encryption-in-transit\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-06\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST NOT expose sensitive information in URLs, query strings, logs, or unnecessary response fields.\",\r\n \"relatedAuditItems\": [\r\n \"no-sensitive-data-in-urls\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-07\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API SHOULD use UUIDs or other non-sequential public identifiers where direct database identifiers would increase exposure risk.\",\r\n \"relatedAuditItems\": [\r\n \"pseudo-identifiers\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-08\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST implement CSRF protection where relevant to the authentication model and client interaction pattern.\",\r\n \"relatedAuditItems\": [\r\n \"csrf-protection\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST define and enforce rate limits, throttling, or quotas according to capacity expectations.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST implement resilience controls such as timeouts, fallback behavior, and degradation handling according to business impact.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-OBS-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"observability\",\r\n \"requirement\": \"The REST API MUST implement logs, metrics, and monitoring needed to observe validation failures, auth failures, traffic, latency, and dependency health.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published through an API management platform.\",\r\n \"relatedAuditItems\": [\r\n \"published-via-api-management\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be accessible only through approved API gateway paths and managed entry points.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API SHOULD be visible in a developer portal with documentation generated from the contract.\",\r\n \"relatedAuditItems\": [\r\n \"visible-in-dev-portal\",\r\n \"docs-auto-generated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published under an approved organizational domain.\",\r\n \"relatedAuditItems\": [\r\n \"official-domain\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate the specification, schema, and examples on every change.\",\r\n \"relatedAuditItems\": [\r\n \"spec-validated-on-change\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST pass concept, design, security, and production-readiness checks before release.\",\r\n \"relatedAuditItems\": [\r\n \"concept-items-audited\",\r\n \"design-items-audited\"\r\n ]\r\n }\r\n ]\r\n}\r\n", "draft": false }, { "id": "api-compliance-best-practices", "slug": "resources/api-compliance-best-practices", "title": "Boas práticas de conformidade da API", "description": "Garantir que as APIs cumprem conformidade legal, regulamentar e interna através de documentação, controlos e validações automatizadas.", "category": "guideline", "icon": "edit-document-outline", "order": 104, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de conformidade da API", "Abordagem normalizada utilizando as Melhores Práticas de Conformidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Documentar as medidas de conformidade e garantir que são comunicadas às partes interessadas e aos utilizadores.", "Implementar medidas para garantir que as APIs cumprem estes requisitos, incluindo encriptação de dados, controlos de acesso e pistas de auditoria.", "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "service-agreement-template", "slug": "resources/service-agreement-template", "title": "Modelo de contrato de serviço", "description": "Um formato de acordo personalizável que define expectativas, SLAs, responsabilidades e termos de acesso para o consumo de API.", "category": "guideline", "icon": "edit-document-outline", "order": 172, "outcomes": [ "Melhor compreensão dos princípios do modelo de contrato de prestação de serviços", "Abordagem normalizada utilizando o modelo de contrato de serviços", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Defina acordos de serviço que descrevam as expectativas, os níveis de serviço e as responsabilidades de cada API.", "Utilize formatos normalizados para criar contratos de serviço legíveis por máquina que sejam fáceis de partilhar e validar.", "Assegurar que os acordos de serviço são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-metrics-and-analytics", "slug": "resources/api-metrics-and-analytics", "title": "Métricas e análise de API", "description": "Um recurso para definir, recolher e analisar o desempenho da API e os dados de utilização para alinhar os KPIs técnicos com os resultados de negócio.", "category": "guideline", "icon": "edit-document-outline", "order": 119, "outcomes": [ "Melhor compreensão dos princípios de métrica e análise de API", "Abordagem normalizada utilizando métricas e análise de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação" ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-community-engagement-strategies", "slug": "resources/api-community-engagement-strategies", "title": "Estratégias de envolvimento da comunidade API", "description": "Um manual para promover a adoção de APIs, cultivando comunidades através de conteúdos, canais de apoio, ciclos de feedback e estratégias de envolvimento social.", "category": "guideline", "icon": "edit-document-outline", "order": 103, "outcomes": [ "Melhor compreensão dos princípios das estratégias de envolvimento da comunidade da API", "Abordagem normalizada utilizando as estratégias de envolvimento da comunidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Desenvolver estratégias de marketing para promover as APIs junto de públicos-alvo, incluindo redes sociais, blogues e webinars.", "Criar materiais promocionais (por exemplo, estudos de casos, histórias de sucesso) que realcem o valor e as vantagens das APIs.", "Criar materiais educativos (por exemplo, tutoriais, documentação) que expliquem as características, as vantagens e os padrões de utilização da API.", "Interagir com os utilizadores da API através de ciclos de feedback, canais de apoio e fóruns da comunidade para compreender as suas necessidades e melhorar a adoção da API.", "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "promptIds": [ "operations-specialist:facilitate-station", "operations-specialist:use-resources", "operations-specialist:next-actions" ] } ], "resources": [ { "id": "customerJourneyCanvas", "slug": "resources/customer-journey-canvas", "title": "Canvas do Percurso do Cliente", "description": "Mapear os percursos dos clientes para identificar necessidades e pontos problemáticos, melhorando a conceção da API e a experiência do utilizador.", "category": "canvas", "icon": "dashboard-outline", "order": 1, "outcomes": [ "Melhoria da compreensão do cliente", "Conceção melhorada da API", "Melhor experiência do utilizador" ], "steps": [ "Definir a personalidade do cliente", "Identificar os factores que desencadeiam a viagem", "Descrever o fim da viagem", "Mapear as etapas do percurso com entradas/saídas", "Identificar os problemas dos clientes", "Resumir os ganhos dos clientes", "Definir os inputs necessários e os outputs resultantes", "Definir interações API para cada etapa" ], "canvasId": "customerJourneyCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "apiValuePropositionCanvas", "slug": "resources/api-value-proposition-canvas", "title": "Canvas da Proposta de Valor da API", "description": "Alinhar as funcionalidades da API com as necessidades dos utilizadores, mapeando tarefas, problemas e ganhos para os produtos da API.", "category": "canvas", "icon": "dashboard-outline", "order": 2, "outcomes": [ "Desenvolvimento de funcionalidades específicas", "Alinhamento com as necessidades dos utilizadores", "Melhoria da satisfação do utilizador da API" ], "steps": [ "Listar as tarefas do percurso do utilizador", "Identificar as características que proporcionam os ganhos esperados", "Definir características para enfrentar os desafios", "Mapear características para produtos API" ], "canvasId": "apiValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityValuePropositionCanvas", "slug": "resources/capability-value-proposition-canvas", "title": "Canvas da Proposta de Valor da Capacidade", "description": "Um canvas independente da tecnologia para mapear tarefas, ganhos, dores e capacidades reutilizáveis candidatas dos utilizadores antes de selecionar um estilo de implementação.", "category": "canvas", "icon": "dashboard-outline", "order": 2.1, "outcomes": [ "Proposta de valor clara para a capacidade reutilizável", "Tarefas, ganhos e dores dos utilizadores captados sem assumir uma tecnologia", "Capacidades reutilizáveis candidatas identificadas para avaliação de arquitetura" ], "steps": [ "Liste as tarefas e resultados dos utilizadores que a capacidade deve suportar.", "Identifique funcionalidades da capacidade que permitem ganhos.", "Identifique funcionalidades da capacidade que aliviam dores.", "Agrupe as funcionalidades em capacidades reutilizáveis candidatas." ], "canvasId": "capabilityValuePropositionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "apiBusinessModelCanvas", "slug": "resources/api-business-model-canvas", "title": "Canvas do Modelo de Negócio da API", "description": "Avaliar estrategicamente a viabilidade do negócio de API, mapeando propostas de valor, segmentos de utilizadores e recursos-chave.", "category": "canvas", "icon": "dashboard-outline", "order": 3, "outcomes": [ "Estratégia comercial clara para APIs", "Identificação dos principais recursos e parceiros", "Alinhamento das características da API com os objetivos de negócio" ], "steps": [ "Resumir a proposta de valor da API", "Definir segmentos de utilizadores", "Identificar estratégias de relações com os promotores", "Mapear os canais de distribuição", "documentar os principais recursos e actividades", "Identificar os principais parceiros e partes interessadas", "Destacar os benefícios e os custos" ], "canvasId": "apiBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capabilityBusinessModelCanvas", "slug": "resources/capability-business-model-canvas", "title": "Canvas do Modelo de Negócio da Capacidade", "description": "Um canvas de modelo de negócio para capacidades de integração reutilizáveis, cobrindo valor, utilizadores, propriedade, envolvimento, custos e benefícios sem assumir disponibilização por API.", "category": "canvas", "icon": "dashboard-outline", "order": 3.1, "outcomes": [ "Modelo operacional viável para a capacidade reutilizável", "Propriedade, utilizadores, canais, parceiros e necessidades de suporte clarificados", "Custos e benefícios visíveis antes do compromisso com a arquitetura" ], "steps": [ "Resuma a proposta de valor da capacidade.", "Identifique segmentos de utilizadores e canais de envolvimento.", "Defina atividades, recursos e parceiros-chave.", "Capte custos e benefícios.", "Clarifique propriedade, financiamento, suporte e expectativas de ciclo de vida.", "Valide o modelo com utilizadores, produtores e partes interessadas de governação." ], "canvasId": "capabilityBusinessModelCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "consumerExperienceRequirementsCanvas", "slug": "resources/consumer-experience-requirements-canvas", "title": "Canvas de Requisitos da Experiência do Utilizador", "description": "Um canvas de requisitos para a experiência orientada para os utilizadores e necessidades não funcionais que deve orientar a escolha de arquitetura posterior.", "category": "canvas", "icon": "dashboard-outline", "order": 3.2, "outcomes": [ "Requisitos dos utilizadores independentes da tecnologia", "Necessidades de experiência e não funcionais captadas antes do início da conceção", "Implicações de arquitetura documentadas para a seleção do estilo" ], "steps": [ "Capte objetivos dos utilizadores e contexto de utilização.", "Documente expectativas de disponibilidade, atualidade, volume, desempenho, qualidade dos dados e consistência.", "Documente expectativas de segurança, privacidade, integração, mudança, observabilidade, suporte e recuperação.", "Resuma o que os requisitos implicam para possíveis estilos de arquitetura." ], "canvasId": "consumerExperienceRequirementsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "businessImpactCanvas", "slug": "resources/business-impact-canvas", "title": "Canvas de Impacto no Negócio", "description": "Conceber uma arquitetura de plataforma API escalável e segura que satisfaça os requisitos de negócio e técnicos.", "category": "canvas", "icon": "dashboard-outline", "order": 4, "outcomes": [ "Infraestrutura API escalável", "Segurança e conformidade melhoradas", "Desempenho melhorado da API" ], "steps": [ "Riscos de disponibilidade: Identificar riscos e impactos.", "Formas de mitigar os riscos de disponibilidade: Definir medidas de mitigação.", "Riscos de segurança: Documentar os riscos relacionados com a segurança.", "Formas de mitigar os riscos de segurança: Propor estratégias para mitigar os riscos de segurança.", "Riscos dos dados: Identificar os riscos para a exatidão ou disponibilidade dos dados.", "Formas de mitigar os riscos dos dados: Planear estratégias para lidar com os riscos dos dados." ], "canvasId": "businessImpactCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "locationsCanvas", "slug": "resources/location-canvas", "title": "Canvas de Localização", "description": "Mapeie as localizações dos fornecedores e utilizadores de API para garantir a conformidade e o desempenho em todas as regiões.", "category": "canvas", "icon": "dashboard-outline", "order": 6, "outcomes": [ "Conformidade com a regulamentação local", "Desempenho optimizado da API em todas as regiões", "Melhoria da compreensão das necessidades regionais" ], "steps": [ "Mapa de localização dos fornecedores de API.", "Documentar a localização dos utilizadores.", "Identificar os regulamentos aplicáveis.", "Documentar onde os dados devem residir.", "Assegurar que as APIs estão acessíveis em todas as regiões da rede previstas.", "Validar o desempenho da rede em todas as regiões." ], "canvasId": "locationsCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "capacityCanvas", "slug": "resources/capacity-canvas", "title": "Canvas de Capacidade", "description": "Planear a capacidade da API para satisfazer as exigências de negócio actuais e futuras, garantindo a escalabilidade e o desempenho.", "category": "canvas", "icon": "dashboard-outline", "order": 7, "outcomes": [ "Alinhamento da capacidade da API com os volumes de negócios", "Preparado para as futuras tendências de consumo", "Estratégias definidas de armazenamento em cache e limitação de taxa" ], "steps": [ "Documentar os volumes de negócios actuais", "Prever as tendências de consumo futuras", "Planear os picos de carga e os requisitos de disponibilidade", "Definir estratégias de armazenamento em cache e de limitação de taxa", "Propor estratégias de escalonamento" ], "canvasId": "capacityCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "interactionCanvas", "slug": "resources/interaction-canvas", "title": "Canvas de Interação", "description": "Definir interações API, fluxos de trabalho e respostas esperadas para garantir uma experiência consistente do utilizador API.", "category": "canvas", "icon": "dashboard-outline", "order": 9, "outcomes": [ "Fluxos de trabalho de interação API claros", "Entradas e saídas definidas para cada interação", "Regras de validação consistentes em todas as interações" ], "steps": [ "Mapear as interações da API para as tarefas do utilizador", "Definir pontos finais para cada interação", "documentar os inputs e outputs de cada interação", "Especificar regras de validação e restrições", "Criar modelos de interação para interações CRUD, orientadas para a consulta, orientadas para o comando e orientadas para o evento" ], "canvasId": "interactionCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "restCanvas", "slug": "resources/rest-canvas", "title": "Canvas REST", "description": "Conceber APIs utilizando os princípios RESTful, definindo recursos, verbos e exemplos de pedidos e respostas.", "category": "canvas", "icon": "dashboard-outline", "order": 10, "outcomes": [ "Conceção consistente da API RESTful", "Recursos definidos e suas interações", "Exemplos de pedidos e respostas para maior clareza" ], "steps": [ "Identificar os principais recursos expostos pela API", "Definir a estrutura do modelo de recursos da API", "Especificar os verbos HTTP utilizados para interagir com os recursos", "Fornecer exemplos de pedidos e respostas para cada verbo" ], "canvasId": "restCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "graphqlCanvas", "slug": "resources/graphql-canvas", "title": "Canvas GraphQL", "description": "Conceber APIs GraphQL definindo tipos, consultas, mutações e subscrições.", "category": "canvas", "icon": "dashboard-outline", "order": 11, "outcomes": [ "Conceção da API GraphQL estruturada", "Tipos definidos e suas relações", "Limpar consultas, mutações e subscrições" ], "steps": [ "Que problemas estão os utilizadores de API a tentar resolver? De que dados necessitam?", "Definir tipos GraphQL e seus atributos: Quais são os principais tipos expostos (por exemplo, utilizador, encomenda, produto)?", "Mapear relações entre tipos: Como é que os tipos se relacionam uns com os outros em consultas aninhadas?", "Especificar consultas para a recuperação de dados", "Definir mutações para a modificação de dados: Que operações irão modificar os dados (por exemplo, criar, atualizar, eliminar)?", "Assinaturas de esboços para actualizações em tempo real", "Definir autenticação e autorização: Quem pode aceder a que campos ou tipos?", "Considerar se existem restrições de paginação, filtragem ou limitação de taxa" ], "canvasId": "graphqlCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "eventCanvas", "slug": "resources/event-canvas", "title": "Canvas de Eventos", "description": "Conceber APIs orientadas para eventos, definindo eventos, accionadores e lógica de processamento.", "category": "canvas", "icon": "dashboard-outline", "order": 12, "outcomes": [ "Arquitetura orientada para eventos definida", "Limpar os accionadores de eventos e a lógica de processamento", "Melhoria da capacidade de resposta a alterações em tempo real" ], "steps": [ "Identificar os principais eventos do sistema", "Definir accionadores para cada evento", "Descrever a lógica de processamento back-end para eventos", "Especificar os resultados ou reconhecimentos resultantes" ], "canvasId": "eventCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "api-audit-checklist", "slug": "resources/api-audit-checklist", "title": "Lista de verificação de auditoria da API", "description": "Uma lista de verificação baseada no ciclo de vida para verificar a prontidão da API em design, entrega, publicação e conformidade utilizando critérios de auditoria e evidências definidos.", "category": "checklist", "icon": "check-box-outline", "order": 13, "outcomes": [ "Melhor compreensão dos princípios da lista de controlo de auditoria da API", "Abordagem normalizada utilizando a lista de verificação de auditoria da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilize a lista de verificação de auditoria da API para garantir que a conceção da API cumpre os requisitos funcionais e não funcionais, incluindo segurança, desempenho e conformidade.", "Realize auditorias para avaliar a cobertura do ciclo de vida e verificar se a API satisfaz os padrões de negócio, conceção e operacionais.", "Certifique-se de que a documentação, os modelos de segurança, a configuração do gateway e os requisitos legais estejam claramente definidos, validados e comprovados por evidências." ], "canvasId": null, "sourcePath": "src/snippets/api-audit-checklist.json", "sourceUrl": null, "contentMarkdown": "{\r\n \"profiles\": {\r\n \"read-only\": {\r\n \"description\": \"API profile that is read-only and does not allow create, update, or delete operations.\"\r\n },\r\n \"full-crud\": {\r\n \"description\": \"General API profile that allows create, update, and delete operations.\"\r\n }\r\n },\r\n \"lifecycleStages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6\r\n }\r\n ],\r\n \"stages\": [\r\n {\r\n \"id\": \"strategy\",\r\n \"title\": \"Strategy\",\r\n \"readinessLabel\": \"Strategy is Ready When...\",\r\n \"order\": 1,\r\n \"items\": [\r\n {\r\n \"id\": \"based-on-clear-business-needs\",\r\n \"label\": \"API is based on clear business needs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiBusinessModelCanvas\",\r\n \"apiValuePropositionCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"design-artifact\",\r\n \"documentation\",\r\n \"research\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\",\r\n \"specs/canvases/api-product-strategy/apiBusinessModelCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"concept-items-audited\",\r\n \"label\": \"All concept checklist items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"strategy\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"strategy\",\r\n \"producedByStation\": [\r\n \"api-product-strategy\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"business-goals-defined\",\r\n \"market-research-done\",\r\n \"stakeholder-approval\",\r\n \"metrics-feedback-available\",\r\n \"api-opportunity-documented\",\r\n \"api-reusability\",\r\n \"value-prop-validated\",\r\n \"consumer-segments-identified\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/concept-review-report.json\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"architecture\",\r\n \"title\": \"Architecture\",\r\n \"readinessLabel\": \"Architecture is Ready When...\",\r\n \"order\": 2,\r\n \"items\": [\r\n {\r\n \"id\": \"versioning-decided\",\r\n \"label\": \"Versioning strategy decided and supported by gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VERSION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-versioning-best-practices\",\r\n \"apiops-CI-CD-for-apis\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"ci-cd\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"only-via-gateway\",\r\n \"label\": \"Only accessible via API gateway\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-reusability\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-02\",\r\n \"REST-CAPACITY-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"businessImpactCanvas\",\r\n \"locationsCanvas\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"infra-config\",\r\n \"security-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/architecture/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"rate-limits-enforced\",\r\n \"label\": \"Rate limits are enforced\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"architecture\",\r\n \"producedByStation\": [\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-roadmap-defined\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CAPACITY-01\",\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"capacityCanvas\",\r\n \"api-security-best-practices\",\r\n \"scalable-infrastructure-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"runtime\",\r\n \"monitoring\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-platform-architecture/capacityCanvas.empty.json\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"design\",\r\n \"title\": \"Design\",\r\n \"readinessLabel\": \"Design is Ready When...\",\r\n \"order\": 3,\r\n \"items\": [\r\n {\r\n \"id\": \"endpoint-descriptions-present\",\r\n \"label\": \"Endpoints have business value and feature descriptions\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"operationDescriptions\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\",\r\n \"api-opportunity-documented\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiValuePropositionCanvas\",\r\n \"customerJourneyCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"hides-raw-backend-data\",\r\n \"label\": \"API hides raw backend data and is designed for shared use\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"interactionCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-product-strategy/domainCanvas.empty.json\",\r\n \"specs/canvases/api-design/interactionCanvas.empty.json\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"design-consistent\",\r\n \"label\": \"API design is consistent with other APIs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-platform-architecture\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-reusability\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DOMAIN-02\",\r\n \"REST-CX-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"design-artifact\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/canvases/api-design/restCanvas.empty.json\",\r\n \"docs/api/design/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"descriptive-english-naming\",\r\n \"label\": \"Data and attribute naming uses descriptive English\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"fieldNamesDescriptive\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"mandatory-fields-specified\",\r\n \"label\": \"Mandatory fields are specified\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"requiredFieldsPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"dates-use-iso\",\r\n \"label\": \"Dates use ISO format with timezone\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"dateFormatTimezone\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"general-data-uses-standard-values\",\r\n \"label\": \"General data uses standard values\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"standardizedEnumsOrPatterns\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-DATA-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"field-names-avoid-acronyms\",\r\n \"label\": \"Field names avoid acronyms and use full words\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"avoidAcronyms\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-NAMING-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"create-returns-identifiers\",\r\n \"label\": \"Creating new resources returns identifiers\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is read-only and does not create resources.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"paths-max-two-resources\",\r\n \"label\": \"Endpoint paths contain max two resources or sub-resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"pathDepthMax\",\r\n \"maxDepth\": 2\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PATH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"examples-present\",\r\n \"label\": \"Endpoints and attributes include examples\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CX-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-for-create-update\",\r\n \"label\": \"POST is used for create or update\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose create or update operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"design-reflects-business-value\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-for-remove\",\r\n \"label\": \"DELETE is used to remove resources\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose delete operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-no-request-body\",\r\n \"label\": \"GET has no request body and returns content\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"getNoRequestBody\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"get-empty-returns-204\",\r\n \"label\": \"GET returns 204 if response body is empty\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current contract returns content for all GET operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-200\",\r\n \"label\": \"POST returns 200 OK when updating\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST updates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-200-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"post-returns-201\",\r\n \"label\": \"POST returns 201 Created with ID on create\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose POST creates.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-201-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"delete-returns-204\",\r\n \"label\": \"DELETE returns 204 on success\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"Read-only profile does not expose DELETE operations.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-RESP-204-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-onboarding-best-practices\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"400-errors-specific\",\r\n \"label\": \"400 errors provide specific error information\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"errorResponsesSpecific\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-consumer-experience\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"design-reflects-business-value\",\r\n \"api-consistency\",\r\n \"value-prop-validated\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-400-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"restCanvas\",\r\n \"api-audit-checklist\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"401-unauthorized\",\r\n \"label\": \"401 Unauthorized for wrong credentials\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current public storefront contract is intentionally unauthenticated.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-401-01\",\r\n \"REST-SEC-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"403-forbidden\",\r\n \"label\": \"403 Forbidden for unauthorized operations\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"The current profile is public read-only and exposes no unauthorized operations.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-ERROR-403-01\",\r\n \"REST-SEC-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-contains-schemas\",\r\n \"label\": \"Spec contains request and response schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"schemasPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"restCanvas\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"contract\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"pseudo-identifiers\",\r\n \"label\": \"UUIDs or pseudo-identifiers instead of DB IDs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"opaqueIdentifiers\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-07\"\r\n ],\r\n \"resourceSource\": [\r\n \"domainCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"no-sensitive-data-in-urls\",\r\n \"label\": \"No sensitive data in URLs\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"noSensitiveDataInPaths\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"hide-backend-discrepancies\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-06\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"contract-first-design\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"http-methods-match-resources\",\r\n \"label\": \"HTTP methods only for intended resources\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"methodResourceConsistency\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"design\",\r\n \"producedByStation\": [\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-HTTP-GET-01\",\r\n \"REST-HTTP-POST-01\",\r\n \"REST-HTTP-PUT-01\",\r\n \"REST-HTTP-DELETE-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"restCanvas\",\r\n \"api-design-principles\",\r\n \"contract-first-design\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"delivery\",\r\n \"title\": \"Delivery\",\r\n \"readinessLabel\": \"Delivery is Ready When...\",\r\n \"order\": 4,\r\n \"items\": [\r\n {\r\n \"id\": \"design-items-audited\",\r\n \"label\": \"All prototype and design items are audited\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"aggregate\",\r\n \"check\": {\r\n \"type\": \"stageCoverage\",\r\n \"stageId\": \"design\"\r\n },\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-design\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"design-reflects-business-value\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"report\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"audit/production-readiness-review.json\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-validated-on-change\",\r\n \"label\": \"Spec validated on every change\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"validationWorkflowPresent\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-audit-checklist\",\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"schema-and-examples-pass\",\r\n \"label\": \"Schema and examples pass validation\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"openapi\",\r\n \"check\": {\r\n \"type\": \"examplesPassValidation\"\r\n },\r\n \"automationLevel\": \"auto\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-design\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-consistency\",\r\n \"architecture-patterns-validated\",\r\n \"api-contract-tested\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-AUDIT-01\",\r\n \"REST-CONTRACT-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"api-audit-checklist\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"test\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"uses-https\",\r\n \"label\": \"Uses HTTPS or encrypted protocols\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"auth-protection\",\r\n \"label\": \"Endpoints protected by authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"gateway-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"token-auth\",\r\n \"label\": \"Token-based authentication\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"csrf-protection\",\r\n \"label\": \"Protected against CSRF\",\r\n \"applicableTo\": [\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"This profile is intentionally public read-only.\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-08\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-development-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"inputs-auto-validated\",\r\n \"label\": \"Inputs auto-validated by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-VALIDATION-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"contract-first-design\",\r\n \"api-testing-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\",\r\n \"test\",\r\n \"spec\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"outputs-auto-escaped\",\r\n \"label\": \"Outputs auto-escaped by framework\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"n/a\",\r\n \"defaultStatus\": \"na\",\r\n \"reason\": \"JSON APIs do not typically require output escaping in the same way as HTML rendering.\",\r\n \"automationLevel\": \"manual\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-development-best-practices\",\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"code\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"encryption-in-transit\",\r\n \"label\": \"Encryption for data in transit and storage\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\",\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-SEC-05\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"data-privacy-guidelines\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"infra-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"message-integrity\",\r\n \"label\": \"Message integrity implemented\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"delivery\",\r\n \"producedByStation\": [\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"architecture-patterns-validated\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-OBS-01\",\r\n \"REST-SEC-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-security-best-practices\",\r\n \"api-compliance-best-practices\",\r\n \"api-metrics-and-analytics\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"security-config\",\r\n \"monitoring\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/delivery/README.md\",\r\n \"docs/api/architecture/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"publishing\",\r\n \"title\": \"Publishing\",\r\n \"readinessLabel\": \"Publishing is Ready When...\",\r\n \"order\": 5,\r\n \"items\": [\r\n {\r\n \"id\": \"published-via-api-management\",\r\n \"label\": \"Published via API management\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-01\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"gateway-config\",\r\n \"ci-cd\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"visible-in-dev-portal\",\r\n \"label\": \"Visible in developer portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-community-engagement-strategies\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"docs-auto-generated\",\r\n \"label\": \"Docs auto-generated from spec and schema\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"partial\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-documentation-ready\",\r\n \"api-ready-for-publishing\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\",\r\n \"REST-PUBLISH-03\"\r\n ],\r\n \"resourceSource\": [\r\n \"contract-first-design\",\r\n \"apiops-CI-CD-for-apis\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"spec\",\r\n \"documentation\",\r\n \"ci-cd\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"specs/openapi/api.yaml\",\r\n \"docs/api/publishing/README.md\",\r\n \"docs/api/audit/design-audit.read-only.md\"\r\n ]\r\n },\r\n {\r\n \"id\": \"spec-auto-updated\",\r\n \"label\": \"Spec auto-updated to gateway and dev portal\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\",\r\n \"api-delivery\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\",\r\n \"api-consistency\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-CONTRACT-02\"\r\n ],\r\n \"resourceSource\": [\r\n \"apiops-CI-CD-for-apis\",\r\n \"contract-first-design\",\r\n \"api-onboarding-best-practices\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"ci-cd\",\r\n \"gateway-config\",\r\n \"documentation\"\r\n ],\r\n \"expectedEvidence\": [\r\n \".github/workflows/openapi-lint.yml\",\r\n \"docs/api/publishing/README.md\",\r\n \"specs/openapi/api.yaml\"\r\n ]\r\n },\r\n {\r\n \"id\": \"official-domain\",\r\n \"label\": \"Published under official organization domain\",\r\n \"applicableTo\": [\r\n \"read-only\",\r\n \"full-crud\"\r\n ],\r\n \"kind\": \"manual\",\r\n \"defaultStatus\": \"gap\",\r\n \"automationLevel\": \"semi\",\r\n \"primaryStage\": \"publishing\",\r\n \"producedByStation\": [\r\n \"api-publishing\"\r\n ],\r\n \"producedByStationCriteria\": [\r\n \"api-ready-for-publishing\",\r\n \"audit-passed\"\r\n ],\r\n \"guidelines\": [\r\n \"REST-PUBLISH-04\"\r\n ],\r\n \"resourceSource\": [\r\n \"api-onboarding-best-practices\",\r\n \"api-audit-checklist\"\r\n ],\r\n \"expectedEvidenceTags\": [\r\n \"documentation\",\r\n \"runtime\"\r\n ],\r\n \"expectedEvidence\": [\r\n \"docs/api/publishing/README.md\"\r\n ]\r\n }\r\n ]\r\n },\r\n {\r\n \"id\": \"improving\",\r\n \"title\": \"Improving\",\r\n \"readinessLabel\": \"Improving is Ready When...\",\r\n \"order\": 6,\r\n \"items\": []\r\n }\r\n ],\r\n \"guidelines\": [\r\n {\r\n \"id\": \"REST-CONTRACT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST implement endpoints, parameters, request bodies, response bodies, and error responses as defined in the validated OpenAPI contract.\",\r\n \"relatedAuditItems\": [\r\n \"spec-contains-schemas\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CONTRACT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST keep the implementation, published OpenAPI description, gateway configuration, and developer portal documentation aligned on every change.\",\r\n \"relatedAuditItems\": [\r\n \"docs-auto-generated\",\r\n \"spec-auto-updated\",\r\n \"spec-validated-on-change\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VALIDATION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate path parameters, query parameters, headers, and JSON request bodies against the OpenAPI schema before business processing.\",\r\n \"relatedAuditItems\": [\r\n \"mandatory-fields-specified\",\r\n \"400-errors-specific\",\r\n \"inputs-auto-validated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST expose business-oriented resources and attributes rather than raw backend tables, internal service payloads, or system-specific field names.\",\r\n \"relatedAuditItems\": [\r\n \"based-on-clear-business-needs\",\r\n \"hides-raw-backend-data\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST preserve validated meanings of entities, attributes, statuses, and source-of-truth rules across all endpoints and operations.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\",\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use descriptive English names for resources and attributes.\",\r\n \"relatedAuditItems\": [\r\n \"descriptive-english-naming\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST avoid unexplained acronyms in public field and resource names.\",\r\n \"relatedAuditItems\": [\r\n \"field-names-avoid-acronyms\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use ISO date-time values with timezone information where dates are exposed.\",\r\n \"relatedAuditItems\": [\r\n \"dates-use-iso\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API SHOULD use standard codes, controlled vocabularies, and standardized value sets where applicable.\",\r\n \"relatedAuditItems\": [\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST describe the business value and feature intent of each endpoint or capability.\",\r\n \"relatedAuditItems\": [\r\n \"endpoint-descriptions-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST include examples for endpoints, request bodies, response bodies, and key attributes.\",\r\n \"relatedAuditItems\": [\r\n \"examples-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API SHOULD use consistent pagination, filtering, sorting, and response conventions across resources.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-GET-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use GET for safe read-only operations and MUST NOT define a request body for GET operations.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-POST-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use POST for resource creation and other non-idempotent operations.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-PUT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use PUT only for full resource replacement.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-DELETE-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use DELETE to remove resources.\",\r\n \"relatedAuditItems\": [\r\n \"delete-for-remove\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PATH-01\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"resource-modeling\",\r\n \"requirement\": \"The REST API SHOULD keep endpoint paths shallow and avoid more than two resource or sub-resource levels unless explicitly justified.\",\r\n \"relatedAuditItems\": [\r\n \"paths-max-two-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-200-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 200 OK for successful reads and updates that include a response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"post-returns-200\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-201-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 201 Created and the created resource identifier when a new resource is created.\",\r\n \"relatedAuditItems\": [\r\n \"create-returns-identifiers\",\r\n \"post-returns-201\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 204 No Content for successful delete operations that do not return a body.\",\r\n \"relatedAuditItems\": [\r\n \"delete-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API SHOULD return 204 No Content for successful operations that intentionally return no response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-empty-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-400-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST define 400 Bad Request responses with specific and actionable validation error information.\",\r\n \"relatedAuditItems\": [\r\n \"400-errors-specific\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-401-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 401 Unauthorized for missing or invalid credentials.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-403-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 403 Forbidden for authenticated clients lacking sufficient permission.\",\r\n \"relatedAuditItems\": [\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VERSION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"versioning\",\r\n \"requirement\": \"The REST API MUST define a versioning strategy before production release, and the strategy MUST be supportable by the API gateway.\",\r\n \"relatedAuditItems\": [\r\n \"versioning-decided\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST require authentication for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use token-based authentication or another approved modern authentication mechanism for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"token-auth\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-03\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST enforce object-level and function-level authorization on every protected operation.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\",\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST mitigate OWASP API risks including broken object level authorization, broken function level authorization, injection, and unrestricted resource consumption.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"rate-limits-enforced\",\r\n \"no-sensitive-data-in-urls\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-05\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use HTTPS or another approved encrypted protocol for all traffic.\",\r\n \"relatedAuditItems\": [\r\n \"uses-https\",\r\n \"encryption-in-transit\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-06\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST NOT expose sensitive information in URLs, query strings, logs, or unnecessary response fields.\",\r\n \"relatedAuditItems\": [\r\n \"no-sensitive-data-in-urls\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-07\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API SHOULD use UUIDs or other non-sequential public identifiers where direct database identifiers would increase exposure risk.\",\r\n \"relatedAuditItems\": [\r\n \"pseudo-identifiers\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-08\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST implement CSRF protection where relevant to the authentication model and client interaction pattern.\",\r\n \"relatedAuditItems\": [\r\n \"csrf-protection\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST define and enforce rate limits, throttling, or quotas according to capacity expectations.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST implement resilience controls such as timeouts, fallback behavior, and degradation handling according to business impact.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-OBS-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"observability\",\r\n \"requirement\": \"The REST API MUST implement logs, metrics, and monitoring needed to observe validation failures, auth failures, traffic, latency, and dependency health.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published through an API management platform.\",\r\n \"relatedAuditItems\": [\r\n \"published-via-api-management\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be accessible only through approved API gateway paths and managed entry points.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API SHOULD be visible in a developer portal with documentation generated from the contract.\",\r\n \"relatedAuditItems\": [\r\n \"visible-in-dev-portal\",\r\n \"docs-auto-generated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published under an approved organizational domain.\",\r\n \"relatedAuditItems\": [\r\n \"official-domain\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate the specification, schema, and examples on every change.\",\r\n \"relatedAuditItems\": [\r\n \"spec-validated-on-change\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST pass concept, design, security, and production-readiness checks before release.\",\r\n \"relatedAuditItems\": [\r\n \"concept-items-audited\",\r\n \"design-items-audited\"\r\n ]\r\n }\r\n ]\r\n}\r\n", "draft": false }, { "id": "api-design-principles", "slug": "resources/api-design-principles", "title": "Princípios de conceção da API", "description": "Um guia conciso sobre usabilidade, descobribilidade e consistência da API, baseado em regras de design partilhadas e nas necessidades reais dos utilizadores.", "category": "guideline", "icon": "edit-document-outline", "order": 14, "outcomes": [ "Melhor compreensão dos princípios de conceção das API", "Abordagem normalizada utilizando os princípios de conceção da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "**Conceção que coloca o utilizador em primeiro lugar:** iniciar cada ciclo de APIOps recolhendo os objetivos do utilizador e os termos do domínio para que as APIs resolvam problemas reais.", "**Nomeação e comportamento consistentes:** aplicar convenções partilhadas para recursos, erros e formatos para tornar as APIs previsíveis.", "**Orientado para contratos:** capturar a interface com OpenAPI ou AsyncAPI antes da codificação para alinhar as equipas e permitir a automatização.", "**Usabilidade e facilidade de descoberta:** fornecer documentação e exemplos claros para que os programadores compreendam rapidamente como utilizar a API.", "**Iterar com segurança:** desenvolver os projetos em pequenos incrementos, com versões, para que as alterações não perturbem os utilizadores existentes." ], "canvasId": null, "sourcePath": "src/snippets/api-style-guide.json", "sourceUrl": null, "contentMarkdown": "{\r\n \"guidelines\": [\r\n {\r\n \"id\": \"REST-CONTRACT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST implement endpoints, parameters, request bodies, response bodies, and error responses as defined in the validated OpenAPI contract.\",\r\n \"relatedAuditItems\": [\r\n \"spec-contains-schemas\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CONTRACT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST keep the implementation, published OpenAPI description, gateway configuration, and developer portal documentation aligned on every change.\",\r\n \"relatedAuditItems\": [\r\n \"docs-auto-generated\",\r\n \"spec-auto-updated\",\r\n \"spec-validated-on-change\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VALIDATION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate path parameters, query parameters, headers, and JSON request bodies against the OpenAPI schema before business processing.\",\r\n \"relatedAuditItems\": [\r\n \"mandatory-fields-specified\",\r\n \"400-errors-specific\",\r\n \"inputs-auto-validated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST expose business-oriented resources and attributes rather than raw backend tables, internal service payloads, or system-specific field names.\",\r\n \"relatedAuditItems\": [\r\n \"hides-raw-backend-data\",\r\n \"design-consistent\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DOMAIN-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST preserve validated meanings of entities, attributes, statuses, and source-of-truth rules across all endpoints and operations.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\",\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use descriptive English names for resources and attributes.\",\r\n \"relatedAuditItems\": [\r\n \"descriptive-english-naming\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-NAMING-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST avoid unexplained acronyms in public field and resource names.\",\r\n \"relatedAuditItems\": [\r\n \"field-names-avoid-acronyms\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API MUST use ISO date-time values with timezone information where dates are exposed.\",\r\n \"relatedAuditItems\": [\r\n \"dates-use-iso\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-DATA-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"domain-modeling\",\r\n \"requirement\": \"The REST API SHOULD use standard codes, controlled vocabularies, and standardized value sets where applicable.\",\r\n \"relatedAuditItems\": [\r\n \"general-data-uses-standard-values\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST describe the business value and feature intent of each endpoint or capability.\",\r\n \"relatedAuditItems\": [\r\n \"endpoint-descriptions-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API MUST include examples for endpoints, request bodies, response bodies, and key attributes.\",\r\n \"relatedAuditItems\": [\r\n \"examples-present\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CX-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"consumer-experience\",\r\n \"requirement\": \"The REST API SHOULD use consistent pagination, filtering, sorting, and response conventions across resources.\",\r\n \"relatedAuditItems\": [\r\n \"design-consistent\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-GET-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use GET for safe read-only operations and MUST NOT define a request body for GET operations.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-POST-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use POST for resource creation and other non-idempotent operations.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-PUT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use PUT only for full resource replacement.\",\r\n \"relatedAuditItems\": [\r\n \"post-for-create-update\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-HTTP-DELETE-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"http-semantics\",\r\n \"requirement\": \"The REST API MUST use DELETE to remove resources.\",\r\n \"relatedAuditItems\": [\r\n \"delete-for-remove\",\r\n \"http-methods-match-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PATH-01\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"resource-modeling\",\r\n \"requirement\": \"The REST API SHOULD keep endpoint paths shallow and avoid more than two resource or sub-resource levels unless explicitly justified.\",\r\n \"relatedAuditItems\": [\r\n \"paths-max-two-resources\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-200-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 200 OK for successful reads and updates that include a response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-no-request-body\",\r\n \"post-returns-200\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-201-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 201 Created and the created resource identifier when a new resource is created.\",\r\n \"relatedAuditItems\": [\r\n \"create-returns-identifiers\",\r\n \"post-returns-201\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API MUST return 204 No Content for successful delete operations that do not return a body.\",\r\n \"relatedAuditItems\": [\r\n \"delete-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-RESP-204-02\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"status-codes\",\r\n \"requirement\": \"The REST API SHOULD return 204 No Content for successful operations that intentionally return no response body.\",\r\n \"relatedAuditItems\": [\r\n \"get-empty-returns-204\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-400-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST define 400 Bad Request responses with specific and actionable validation error information.\",\r\n \"relatedAuditItems\": [\r\n \"400-errors-specific\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-401-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 401 Unauthorized for missing or invalid credentials.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-ERROR-403-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"error-handling\",\r\n \"requirement\": \"The REST API MUST return 403 Forbidden for authenticated clients lacking sufficient permission.\",\r\n \"relatedAuditItems\": [\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-VERSION-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"versioning\",\r\n \"requirement\": \"The REST API MUST define a versioning strategy before production release, and the strategy MUST be supportable by the API gateway.\",\r\n \"relatedAuditItems\": [\r\n \"versioning-decided\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST require authentication for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use token-based authentication or another approved modern authentication mechanism for protected endpoints.\",\r\n \"relatedAuditItems\": [\r\n \"token-auth\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-03\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST enforce object-level and function-level authorization on every protected operation.\",\r\n \"relatedAuditItems\": [\r\n \"401-unauthorized\",\r\n \"403-forbidden\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST mitigate OWASP API risks including broken object level authorization, broken function level authorization, injection, and unrestricted resource consumption.\",\r\n \"relatedAuditItems\": [\r\n \"auth-protection\",\r\n \"rate-limits-enforced\",\r\n \"no-sensitive-data-in-urls\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-05\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST use HTTPS or another approved encrypted protocol for all traffic.\",\r\n \"relatedAuditItems\": [\r\n \"uses-https\",\r\n \"encryption-in-transit\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-06\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST NOT expose sensitive information in URLs, query strings, logs, or unnecessary response fields.\",\r\n \"relatedAuditItems\": [\r\n \"no-sensitive-data-in-urls\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-07\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API SHOULD use UUIDs or other non-sequential public identifiers where direct database identifiers would increase exposure risk.\",\r\n \"relatedAuditItems\": [\r\n \"pseudo-identifiers\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-SEC-08\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"security\",\r\n \"requirement\": \"The REST API MUST implement CSRF protection where relevant to the authentication model and client interaction pattern.\",\r\n \"relatedAuditItems\": [\r\n \"csrf-protection\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST define and enforce rate limits, throttling, or quotas according to capacity expectations.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-CAPACITY-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"resilience-capacity\",\r\n \"requirement\": \"The REST API MUST implement resilience controls such as timeouts, fallback behavior, and degradation handling according to business impact.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\",\r\n \"encryption-in-transit\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-OBS-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"observability\",\r\n \"requirement\": \"The REST API MUST implement logs, metrics, and monitoring needed to observe validation failures, auth failures, traffic, latency, and dependency health.\",\r\n \"relatedAuditItems\": [\r\n \"rate-limits-enforced\",\r\n \"message-integrity\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published through an API management platform.\",\r\n \"relatedAuditItems\": [\r\n \"published-via-api-management\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be accessible only through approved API gateway paths and managed entry points.\",\r\n \"relatedAuditItems\": [\r\n \"only-via-gateway\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-03\",\r\n \"priority\": \"SHOULD\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API SHOULD be visible in a developer portal with documentation generated from the contract.\",\r\n \"relatedAuditItems\": [\r\n \"visible-in-dev-portal\",\r\n \"docs-auto-generated\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-PUBLISH-04\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"publishing-governance\",\r\n \"requirement\": \"The REST API MUST be published under an approved organizational domain.\",\r\n \"relatedAuditItems\": [\r\n \"official-domain\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-01\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST validate the specification, schema, and examples on every change.\",\r\n \"relatedAuditItems\": [\r\n \"spec-validated-on-change\",\r\n \"schema-and-examples-pass\"\r\n ]\r\n },\r\n {\r\n \"id\": \"REST-AUDIT-02\",\r\n \"priority\": \"MUST\",\r\n \"category\": \"contract-governance\",\r\n \"requirement\": \"The REST API MUST pass concept, design, security, and production-readiness checks before release.\",\r\n \"relatedAuditItems\": [\r\n \"concept-items-audited\",\r\n \"design-items-audited\"\r\n ]\r\n }\r\n ]\r\n}", "draft": false }, { "id": "api-community-engagement-strategies", "slug": "resources/api-community-engagement-strategies", "title": "Estratégias de envolvimento da comunidade API", "description": "Um manual para promover a adoção de APIs, cultivando comunidades através de conteúdos, canais de apoio, ciclos de feedback e estratégias de envolvimento social.", "category": "guideline", "icon": "edit-document-outline", "order": 103, "outcomes": [ "Melhor compreensão dos princípios das estratégias de envolvimento da comunidade da API", "Abordagem normalizada utilizando as estratégias de envolvimento da comunidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Desenvolver estratégias de marketing para promover as APIs junto de públicos-alvo, incluindo redes sociais, blogues e webinars.", "Criar materiais promocionais (por exemplo, estudos de casos, histórias de sucesso) que realcem o valor e as vantagens das APIs.", "Criar materiais educativos (por exemplo, tutoriais, documentação) que expliquem as características, as vantagens e os padrões de utilização da API.", "Interagir com os utilizadores da API através de ciclos de feedback, canais de apoio e fóruns da comunidade para compreender as suas necessidades e melhorar a adoção da API.", "Analisar as métricas de utilização da API e incorporar o feedback dos utilizadores nas iterações da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-compliance-best-practices", "slug": "resources/api-compliance-best-practices", "title": "Boas práticas de conformidade da API", "description": "Garantir que as APIs cumprem conformidade legal, regulamentar e interna através de documentação, controlos e validações automatizadas.", "category": "guideline", "icon": "edit-document-outline", "order": 104, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de conformidade da API", "Abordagem normalizada utilizando as Melhores Práticas de Conformidade da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Documentar as medidas de conformidade e garantir que são comunicadas às partes interessadas e aos utilizadores.", "Implementar medidas para garantir que as APIs cumprem estes requisitos, incluindo encriptação de dados, controlos de acesso e pistas de auditoria.", "Utilizar listas de controlo, linters e ferramentas de teste para verificar a consistência e a conformidade com as normas." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-development-best-practices", "slug": "resources/api-development-best-practices", "title": "Boas práticas de desenvolvimento de API", "description": "Orientações de implementação para transformar um contrato de interface da API validado numa base de código de API consistente e sustentável, utilizando bibliotecas padrão, padrões reutilizáveis e fluxos de trabalho de desenvolvimento alinhados.", "category": "guideline", "icon": "edit-document-outline", "order": 112, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de desenvolvimento de API", "Abordagem normalizada utilizando as boas práticas de desenvolvimento de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplique essas práticas ao contrato de interface da API validado e ao plano de implementação antes do início da codificação.", "Utilize frameworks, bibliotecas e padrões de codificação estabelecidos para implementar o contrato de forma consistente e sustentável." ], "canvasId": null, "sourcePath": "src/snippets/pt/api-design-principles-guidance.md", "sourceUrl": null, "contentMarkdown": "## Como iniciar o trabalho de entrega da API com base nas fases anteriores (“etapas”)\r\nUtilize estas orientações no início da `API Delivery` (entrega da API), após a revisão e aceitação do contrato da API (por exemplo, OpenAPI) e dos principais resultados das etapas anteriores.\r\nO objetivo não é desenvolver a implementação de forma isolada. O objetivo é transformar os resultados acordados nas etapas anteriores em uma estrutura de código concreta, regras de validação, comportamento em tempo de execução e decisões relativas à entrega do produto API.\r\n\r\n---\r\n\r\n### 1. Comece a partir do contrato validado\r\n- Trate o contrato de API validado como o principal ponto de referência para as decisões de implementação.\r\n- Mantenha o contrato e a implementação alinhados ao longo de toda a entrega do produto API.\r\n- Use o contrato para orientar a validação de solicitações, o mapeamento de respostas, a documentação e os testes.\r\n\r\n---\r\n\r\n### 2. Use os resultados do domínio para preservar o significado comercial\r\n- Use os resultados do `Domain Canvas` para orientar a nomenclatura, como a implementação é dividida em responsabilidades comerciais claras e como diferentes sistemas de back-end são conectados sem expor suas diferenças.\r\n- Preserve os significados validados de entidades, atributos, status e regras de fonte de verdade.\r\n- Evite vazar modelos específicos do back-end ou inconsistências para a API pública.\r\n\r\n---\r\n\r\n### 3. Use os resultados da jornada para preservar fluxos críticos\r\n- Use os resultados do `Customer Journey Canvas` para identificar quais fluxos de usuários são mais importantes para serem atendidos primeiro.\r\n- Use os resultados da `API Consumer Experience` para manter a API compreensível, previsível e fácil de integrar.\r\n- Deixe que as prioridades de jornada acordadas decidam quais caminhos de implementação precisam da maior confiabilidade, menor latência, erros mais claros e maior foco operacional.\r\n\r\n---\r\n\r\n### 4. Use os resultados da Proposta de Valor para preservar o valor para o consumidor\r\n- Use os resultados do `API Value Proposition Canvas` para manter a implementação focada nas dores, ganhos e recursos da API acordados.\r\n- Preserve os significados dos campos, o comportamento e as promessas que tornaram a API valiosa nas etapas anteriores.\r\n- Garanta que o tratamento de erros, a atualização e a nomenclatura apoiem tanto a experiência do desenvolvedor pretendida quanto o caso de uso de negócios.\r\n\r\n---\r\n\r\n### 5. Use os resultados da arquitetura para moldar as decisões de tempo de execução\r\n- Use os resultados do `Business Impact Canvas` para orientar as decisões sobre resiliência, tempo limite, fallback e degradação.\r\n- Use os resultados do `Locations Canvas` para orientar os limites de rede, limites de confiança, caminhos de acesso e restrições de implantação.\r\n- Use os resultados do `Capacity Canvas` para orientar limites de taxa, cache, escalonamento e comportamento em picos de carga.\r\n- Use as orientações do `API Metrics And Analytics` para decidir o que deve ser observado desde a primeira implementação em diante.\r\n\r\n---\r\n\r\n### 6. Use os resultados do projeto de interação e protocolo para moldar a estrutura do código\r\n- Use os resultados do `Interaction Canvas` para evitar implementar estilos de interação não suportados prematuramente.\r\n- Use os resultados do projeto `REST`, `Event` ou `GraphQL` para moldar o comportamento de solicitação, resposta e validação específico do protocolo.\r\n- Reflete o estilo de interação selecionado claramente na estrutura do código, nas responsabilidades e na estratégia de testes.\r\n\r\n---\r\n\r\n### 7. Usa os resultados da auditoria para melhorar a entrega antes que a codificação avance demais\r\n- Usa as conclusões da auditoria para remover ambiguidades antes que a implementação se espalhe pela base de código.\r\n- Corrige regras de solicitação pouco claras, validações ausentes, contratos de erro fracos e lacunas operacionais logo no início.\r\n- Trate a auditoria como um ciclo de melhoria de projeto antes da produção, não apenas como uma etapa de decisão final.\r\n\r\n---\r\n\r\n### 8. Aplique as orientações e, em seguida, resuma\r\n- Aplique estas orientações à API atual e ao plano de implementação.\r\n- Resuma as implicações para a estrutura do código, validação de solicitações, integração de fontes, segurança, monitoramento e alertas, e testes.\r\n- Não crie um artefato de entrega separado, a menos que a equipe ou o usuário precise especificamente de um.\r\n", "draft": true }, { "id": "api-metrics-and-analytics", "slug": "resources/api-metrics-and-analytics", "title": "Métricas e análise de API", "description": "Um recurso para definir, recolher e analisar o desempenho da API e os dados de utilização para alinhar os KPIs técnicos com os resultados de negócio.", "category": "guideline", "icon": "edit-document-outline", "order": 119, "outcomes": [ "Melhor compreensão dos princípios de métrica e análise de API", "Abordagem normalizada utilizando métricas e análise de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Identificar indicadores-chave de desempenho (KPIs) para medir o sucesso da API em relação aos objetivos de negócio.", "Definir e monitorizar as métricas de desempenho (por exemplo, chamadas APIs, latência, taxas de erro) e as métricas de adoção (por exemplo, NPS).", "Monitorizar as iniciativas APIs para garantir o cumprimento das orientações operacionais e das práticas de governação" ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-onboarding-best-practices", "slug": "resources/api-onboarding-best-practices", "title": "Boas práticas de integração de API", "description": "Boas práticas para simplificar as jornadas de integração do utilizador da API com registo passo a passo, descoberta e orientação na primeira chamada.", "category": "guideline", "icon": "edit-document-outline", "order": 121, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de integração de API", "Abordagem normalizada utilizando as boas práticas de integração de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir o percurso do utilizador da API desde a descoberta até à resolução de problemas, identificando os principais pontos de contacto e os pontos problemáticos.", "Desenvolver processos de integração e recursos para ajudar os utilizadores de API a compreender como utilizar as APIs de forma eficaz.", "Documentar a forma como os utilizadores encontram e utilizam a API, incluindo processos de integração e registo." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-portfolio-management-guidelines", "slug": "resources/api-portfolio-management-guidelines", "title": "Diretrizes de gestão da carteira API", "description": "Um guia para gerir estrategicamente o conjunto de APIs de uma organização - priorizando APIs, alocando recursos e monitorando o desempenho ao longo de todo o ciclo de vida.", "category": "guideline", "icon": "edit-document-outline", "order": 123, "outcomes": [ "Melhor compreensão dos princípios orientadores da gestão de carteiras API", "Abordagem normalizada utilizando as diretrizes de gestão de portfólio da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir práticas de gestão da carteira que descrevam os processos de gestão da carteira de API, incluindo a definição de prioridades, a monitorização e a otimização.", "Definir práticas de gestão orçamental e de recursos que descrevam os processos de gestão de orçamentos e recursos para iniciativas de API.", "Estabelecer critérios para avaliar e dar prioridade às dotações orçamentais com base no valor de negócio, no impacto e no alinhamento com as iniciativas estratégicas.", "Monitorizar a carteira de APIs para garantir que as APIs estão a fornecer valor, a cumprir as expectativas de desempenho e a alinhar-se com os objetivos de negócio." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-security-best-practices", "slug": "resources/api-security-best-practices", "title": "Boas práticas de segurança da API", "description": "Um conjunto de controlos acionáveis para proteger APIs, incluindo autenticação, autorização, encriptação, limitação de taxas e verificações de conformidade ao nível do pipeline.", "category": "guideline", "icon": "edit-document-outline", "order": 130, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de segurança da API", "Abordagem normalizada utilizando as boas práticas de segurança da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Garantir que as APIs cumprem os requisitos de segurança e conformidade através de verificações e auditorias automatizadas.", "Implemente medidas de segurança como autenticação, autorização, encriptação e limitação de taxas para proteger as APIs de ameaças.", "Implementar verificações de segurança automatizadas e validações de conformidade no pipeline CI/CD para garantir que as APIs são seguras e compatíveis." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-team-structure-guidelines", "slug": "resources/api-team-structure-guidelines", "title": "Diretrizes da estrutura da equipa API", "description": "Orientação organizacional para a definição de funções e responsabilidades nas equipas de API para garantir clareza, colaboração e responsabilidade.", "category": "guideline", "icon": "edit-document-outline", "order": 132, "outcomes": [ "Melhor compreensão dos princípios orientadores da estrutura da equipa API", "Abordagem normalizada utilizando as Diretrizes da Estrutura da Equipa API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir estruturas de equipa e funções para equipas de API, incluindo proprietários de produtos de API, programadores, arquitectos e operações." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-testing-best-practices", "slug": "resources/api-testing-best-practices", "title": "Boas práticas de teste de API", "description": "Diretrizes para a implementação de testes automatizados funcionais, de desempenho e de segurança ao longo do ciclo de vida da API.", "category": "guideline", "icon": "edit-document-outline", "order": 133, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de teste de API", "Abordagem normalizada utilizando as boas práticas de teste de API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Testar a funcionalidade, a segurança e o desempenho das APIs, utilizando ferramentas de teste automatizadas.", "Integrar testes funcionais e não funcionais no pipeline CI/CD para garantir que as APIs cumprems normas de qualidade.", "Utilizar ferramentas de teste automatizadas para validar a funcionalidade, a segurança e o desempenho da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-training-programs", "slug": "resources/api-training-programs", "title": "Programas de formação API", "description": "Um roteiro para melhorar as competências das equipas com percursos de aprendizagem estruturados em design, governação, desempenho e segurança de API.", "category": "guideline", "icon": "edit-document-outline", "order": 134, "outcomes": [ "Melhor compreensão dos princípios dos programas de formação API", "Abordagem normalizada utilizando Programas de Formação API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Identificar as principais competências e áreas de conhecimento da API que precisam de ser melhoradas, como a conceção, a segurança e o desempenho da API.", "Incentivar a aprendizagem contínua através de cursos em linha, certificações e envolvimento da comunidade.", "Fornecer formação e recursos para ajudar as equipas a adotar uma mentalidade de prioridade à API e a compreender as vantagens das APIs.", "Fornecer programas de formação, workshops e recursos para ajudar as equipas a melhorar as suas competências e conhecimentos em matéria de API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "api-versioning-best-practices", "slug": "resources/api-versioning-best-practices", "title": "Boas práticas de controlo de versões da API", "description": "Estratégias para introduzir, manter e retirar versões de API, preservando a compatibilidade com versões anteriores e a confiança dos utilizadores.", "category": "guideline", "icon": "edit-document-outline", "order": 138, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de controlo de versões da API", "Abordagem normalizada utilizando as boas práticas de controlo de versões da API", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir estratégias de controlo de versões para as APIs para gerir as alterações e garantir a compatibilidade com as versões anteriores." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "apiops-CI-CD-for-apis", "slug": "resources/apiops-CI-CD-for-apis", "title": "APIOps CI/CD para APIs", "description": "Orientação de disponibilização que integra tarefas do ciclo de vida da API - design, teste, governação - em pipelines de integração e entrega contínuas.", "category": "guideline", "icon": "edit-document-outline", "order": 140, "outcomes": [ "Melhor compreensão dos princípios de CI/CD para APIs", "Abordagem normalizada utilizando CI/CD para APIs", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Utilizar pipelines CI/CD para automatizar os processos de construção, teste e implementação, garantindo uma qualidade e rastreabilidade consistentes.", "Integrar testes automatizados no pipeline CI/CD para garantir a validação contínua da qualidade da API.", "Implementar estratégias de disponibilização (por exemplo, disponibilizações blue-green, lançamentos canários) para minimizar os riscos durante os lançamentos de API.", "Crie o hábito de analisar os indicadores e planear actividades de melhoria contínua." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "competitor-analysis-template", "slug": "resources/competitor-analysis-template", "title": "Modelo de análise da concorrência", "description": "Uma folha de cálculo estruturada para comparar as suas ofertas de API com a concorrência, mapeando os pontos fortes, os pontos fracos e os diferenciadores de valor.", "category": "guideline", "icon": "edit-document-outline", "order": 143, "outcomes": [ "Melhor compreensão dos princípios do modelo de análise da concorrência", "Abordagem normalizada utilizando o modelo de análise da concorrência", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Efetuar uma análise da concorrência para identificar os principais concorrentes e as suas ofertas de API.", "Analisar as APIs da concorrência para compreender os seus pontos fortes, fracos e pontos de venda únicos." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "contract-first-design", "slug": "resources/contract-first-design", "title": "Primeira conceção do contrato", "description": "Uma diretriz que defende abordagens API-first utilizando contratos formais (por exemplo, OpenAPI) para alinhar as partes interessadas antes do desenvolvimento.", "category": "guideline", "icon": "edit-document-outline", "order": 146, "outcomes": [ "Melhor compreensão dos princípios de conceção da primeira fase do contrato", "Abordagem normalizada utilizando a conceção orientada por contrato", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Aplicar abordagens \"contract-first\" ou \"design-first\" para garantir que os contratos de interface da API são validados antes da implementação.", "Definir contratos de interface da API que descrevam as expectativas, responsabilidades e diretrizes de utilização para cada API.", "Utilizar formatos normalizados (por exemplo, OpenAPI, AsyncAPI) para criar contratos de interface da API legíveis por máquina que sejam fáceis de partilhar e validar." ], "canvasId": null, "sourcePath": "src/snippets/api-contract-example.yaml", "sourceUrl": null, "contentMarkdown": "openapi: 3.0.3\r\ninfo:\r\n title: Sample Catalog API\r\n version: 1.0.0\r\n description: |\r\n Starter example for a read-only APIOps Cycles API.\r\n This example keeps the contract audit-friendly and easy to extend.\r\nservers:\r\n - url: /v1\r\n description: Versioned API base path\r\ntags:\r\n - name: catalog\r\n description: Browse and search catalog items\r\npaths:\r\n /items:\r\n get:\r\n tags: [catalog]\r\n summary: List catalog items\r\n description: Returns a paginated list of public catalog items.\r\n operationId: listItems\r\n parameters:\r\n - $ref: \"#/components/parameters/searchTerm\"\r\n - $ref: \"#/components/parameters/categoryId\"\r\n - $ref: \"#/components/parameters/page\"\r\n - $ref: \"#/components/parameters/pageSize\"\r\n responses:\r\n \"200\":\r\n description: Item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n examples:\r\n default:\r\n value:\r\n data:\r\n - itemId: item-123\r\n slug: blue-widget\r\n name: Blue Widget\r\n status: published\r\n page:\r\n number: 1\r\n size: 20\r\n totalItems: 1\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"429\":\r\n $ref: \"#/components/responses/TooManyRequests\"\r\n /items/{itemId}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by id\r\n description: Returns a single public catalog item by opaque identifier.\r\n operationId: getItemById\r\n parameters:\r\n - $ref: \"#/components/parameters/itemId\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"400\":\r\n $ref: \"#/components/responses/BadRequest\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /items/by-slug/{slug}:\r\n get:\r\n tags: [catalog]\r\n summary: Get item by slug\r\n description: Returns a single item by public slug.\r\n operationId: getItemBySlug\r\n parameters:\r\n - $ref: \"#/components/parameters/slug\"\r\n responses:\r\n \"200\":\r\n description: Item details\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemDetail\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\n /categories/{categoryId}/items:\r\n get:\r\n tags: [catalog]\r\n summary: List items in category\r\n description: Returns public items in a category.\r\n operationId: listItemsByCategory\r\n parameters:\r\n - $ref: \"#/components/parameters/categoryId\"\r\n responses:\r\n \"200\":\r\n description: Category item list\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ItemListResponse\"\r\n \"404\":\r\n $ref: \"#/components/responses/NotFound\"\r\ncomponents:\r\n parameters:\r\n itemId:\r\n name: itemId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: item-123\r\n slug:\r\n name: slug\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9]+(?:-[a-z0-9]+)*$\"\r\n example: blue-widget\r\n categoryId:\r\n name: categoryId\r\n in: path\r\n required: true\r\n schema:\r\n type: string\r\n pattern: \"^[a-z0-9][a-z0-9-]{1,63}$\"\r\n example: home-goods\r\n searchTerm:\r\n name: searchTerm\r\n in: query\r\n required: false\r\n schema:\r\n type: string\r\n minLength: 1\r\n example: widget\r\n page:\r\n name: page\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n default: 1\r\n pageSize:\r\n name: pageSize\r\n in: query\r\n required: false\r\n schema:\r\n type: integer\r\n minimum: 1\r\n maximum: 100\r\n default: 20\r\n responses:\r\n BadRequest:\r\n description: Validation failed\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n examples:\r\n default:\r\n value:\r\n code: BAD_REQUEST\r\n message: Invalid request\r\n NotFound:\r\n description: Resource not found\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n TooManyRequests:\r\n description: Rate limit exceeded\r\n headers:\r\n Retry-After:\r\n schema:\r\n type: integer\r\n description: Seconds until the next allowed request.\r\n content:\r\n application/json:\r\n schema:\r\n $ref: \"#/components/schemas/ErrorResponse\"\r\n schemas:\r\n ItemListResponse:\r\n type: object\r\n required: [data, page]\r\n properties:\r\n data:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/ItemSummary\"\r\n page:\r\n $ref: \"#/components/schemas/Page\"\r\n ItemSummary:\r\n type: object\r\n required: [itemId, slug, name, status]\r\n properties:\r\n itemId:\r\n type: string\r\n slug:\r\n type: string\r\n name:\r\n type: string\r\n status:\r\n type: string\r\n enum: [published, hidden]\r\n ItemDetail:\r\n allOf:\r\n - $ref: \"#/components/schemas/ItemSummary\"\r\n - type: object\r\n properties:\r\n description:\r\n type: string\r\n categories:\r\n type: array\r\n items:\r\n type: string\r\n variants:\r\n type: array\r\n items:\r\n $ref: \"#/components/schemas/Variant\"\r\n Variant:\r\n type: object\r\n required: [variantId, sku, price, inventory]\r\n properties:\r\n variantId:\r\n type: string\r\n sku:\r\n type: string\r\n price:\r\n $ref: \"#/components/schemas/Price\"\r\n inventory:\r\n $ref: \"#/components/schemas/Inventory\"\r\n Price:\r\n type: object\r\n required: [amount, currency]\r\n properties:\r\n amount:\r\n type: number\r\n format: decimal\r\n currency:\r\n type: string\r\n example: EUR\r\n Inventory:\r\n type: object\r\n required: [available]\r\n properties:\r\n available:\r\n type: integer\r\n minimum: 0\r\n reserved:\r\n type: integer\r\n minimum: 0\r\n source:\r\n type: string\r\n Page:\r\n type: object\r\n required: [number, size, totalItems]\r\n properties:\r\n number:\r\n type: integer\r\n size:\r\n type: integer\r\n totalItems:\r\n type: integer\r\n ErrorResponse:\r\n type: object\r\n required: [code, message]\r\n properties:\r\n code:\r\n type: string\r\n message:\r\n type: string\r\n", "draft": true }, { "id": "cross-functional-collaboration-best-practices", "slug": "resources/cross-functional-collaboration-best-practices", "title": "Boas práticas de colaboração interfuncional", "description": "Práticas para facilitar a comunicação e o alinhamento entre as equipas de negócio e técnicas ao planear ou fornecer APIs.", "category": "guideline", "icon": "edit-document-outline", "order": 147, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de colaboração interfuncional", "Abordagem normalizada utilizando as boas práticas de colaboração interfuncional", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Incentivar a colaboração multifuncional entre equipas de API, unidades empresariais e partes interessadas para alinhar as iniciativas de API com os objetivos empresariais." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "data-privacy-guidelines", "slug": "resources/data-privacy-guidelines", "title": "Diretrizes de privacidade de dados", "description": "Considerações de design para garantir que as APIs cumprem os regulamentos de proteção de dados, como o RGPD, através de anonimização e controlos de acesso.", "category": "guideline", "icon": "edit-document-outline", "order": 148, "outcomes": [ "Melhor compreensão dos princípios das diretrizes relativas à privacidade dos dados", "Abordagem normalizada utilizando as Diretrizes de Privacidade de Dados", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Garantir a privacidade dos dados dos utilizadores através da implementação de medidas de proteção de dados, como a anonimização e os controlos de acesso." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "domainCanvas", "slug": "resources/domain-canvas", "title": "Canvas de Domínio", "description": "Uma ferramenta de modelação para definir e comunicar as principais entidades e relações no seu domínio, assegurando a consistência semântica entre APIs.", "category": "canvas", "icon": "dashboard-outline", "order": 152, "outcomes": [ "Melhor compreensão dos princípios do domínio canvas", "Abordagem normalizada utilizando o Canvas de Domínio", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Definir entidades principais, os seus atributos e relações para criar um entendimento concetual partilhado entre APIs." ], "canvasId": "domainCanvas", "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": false }, { "id": "ecosystem-vision-template", "slug": "resources/ecosystem-vision-template", "title": "Modelo de visão do ecossistema", "description": "Uma ferramenta de planeamento estratégico para definir o ecossistema API, incluindo parceiros-alvo, cadeias de valor e oportunidades de integração.", "category": "guideline", "icon": "edit-document-outline", "order": 154, "outcomes": [ "Melhor compreensão dos princípios do modelo de visão do ecossistema", "Abordagem normalizada utilizando o Modelo de Visão do Ecossistema", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Realizar estudos de mercado para identificar tendências, oportunidades e ameaças no panorama das APIs.", "Identificar os principais parceiros e intervenientes do ecosistema que irão beneficiar ou contribuir para o ecosistema.", "Identifique as lacunas no mercado que as suas APIs podem preencher, com base nas ofertas da concorrência.", "Identifique potenciais parceiros cujas APIs possam melhorar as suas capacidades de API e a sua proposta de valor.", "Desenvolva uma estratégia de diferenciação que destaque as características e benefícios únicos das suas APIs.", "Defina a visão do ecossistema para as suas APIs, incluindo a forma como estas irão interagir com outros sistemas e plataformas.", "Conceber APIs para permitir uma integração e colaboração perfeitas no ecossistema." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "industry-standards-and-best-practices", "slug": "resources/industry-standards-and-best-practices", "title": "Normas e boas práticas do sector", "description": "Um recurso de referência para alinhar a conceção e a operação da API com estruturas e especificações amplamente reconhecidas do sector.", "category": "guideline", "icon": "edit-document-outline", "order": 157, "outcomes": [ "Melhor compreensão das normas do sector e dos princípios das boas práticas", "Abordagem normalizada utilizando as normas e as boas práticas do sector", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Identificar as normas e as boas práticas do sector para garantir que as APIs são competitivas e estão em conformidade." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "partner-integration-guidelines", "slug": "resources/partner-integration-guidelines", "title": "Diretrizes de integração de parceiros", "description": "Listas de verificação de integração e padrões de comunicação para gerir os aspectos técnicos e legais das relações com APIs de terceiros.", "category": "guideline", "icon": "edit-document-outline", "order": 164, "outcomes": [ "Melhor compreensão dos princípios das diretrizes de integração de parceiros", "Abordagem normalizada utilizando as Diretrizes de Integração de Parceiros", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Estabelecer processos de integração e orientações para colaborar com os parceiros, incluindo a integração técnica, a partilha de dados e o apoio.", "Monitorize o desempenho e a conformidade da API do parceiro para garantir a fiabilidade e o alinhamento com a sua estratégia de API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "role-communication-best-practices", "slug": "resources/role-communication-best-practices", "title": "Boas práticas de comunicação de funções", "description": "Ferramentas para definir e documentar quem é responsável por quê nas iniciativas de API, garantindo que as transferências e a responsabilidade sejam claras.", "category": "guideline", "icon": "edit-document-outline", "order": 167, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de comunicação de funções", "Abordagem normalizada utilizando as boas práticas de comunicação de funções", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Estabelecer responsabilidades claras para cada função, incluindo a conceção, o desenvolvimento, os testes e as operações da API.", "Assegurar que as funções e responsabilidades são comunicadas a todos os membros da equipa e partes interessadas para garantir o alinhamento." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "scalable-infrastructure-best-practices", "slug": "resources/scalable-infrastructure-best-practices", "title": "Boas práticas de infraestrutura escalável", "description": "Orientação arquitetónica para garantir que as APIs são implementadas em infra-estruturas que podem lidar elasticamente com picos de utilização e crescimento.", "category": "guideline", "icon": "edit-document-outline", "order": 168, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de infra-estruturas escaláveis", "Abordagem normalizada utilizando as Melhores Práticas de Infraestrutura Escalável", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Conceber a infraestrutura da API para ser escalável e resiliente, utilizando padrões e tecnologias nativos da nuvem.", "Monitorizar o desempenho e a capacidade da infraestrutura para garantir que esta consegue dar resposta à crescente procura." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "service-agreement-template", "slug": "resources/service-agreement-template", "title": "Modelo de contrato de serviço", "description": "Um formato de acordo personalizável que define expectativas, SLAs, responsabilidades e termos de acesso para o consumo de API.", "category": "guideline", "icon": "edit-document-outline", "order": 172, "outcomes": [ "Melhor compreensão dos princípios do modelo de contrato de prestação de serviços", "Abordagem normalizada utilizando o modelo de contrato de serviços", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Defina acordos de serviço que descrevam as expectativas, os níveis de serviço e as responsabilidades de cada API.", "Utilize formatos normalizados para criar contratos de serviço legíveis por máquina que sejam fáceis de partilhar e validar.", "Assegurar que os acordos de serviço são revistos e aprovados pelas partes interessadas para garantir o alinhamento e a clareza." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "stakeholder-engagement-best-practices", "slug": "resources/stakeholder-engagement-best-practices", "title": "Boas práticas de envolvimento das partes interessadas", "description": "Tácticas de envolvimento para alinhar as partes interessadas internas e externas em torno dos objetivos, valor e governação partilhados da API.", "category": "guideline", "icon": "edit-document-outline", "order": 173, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de envolvimento das partes interessadas", "Abordagem normalizada utilizando as Melhores Práticas de Envolvimento das Partes Interessadas", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Envolver as partes interessadas para garantir o alinhamento e o apoio às iniciativas da API." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "test-automation-frameworks", "slug": "resources/test-automation-frameworks", "title": "Estruturas de automatização de testes", "description": "Ferramentas e padrões recomendados para automatizar testes de contrato, regressão e integração de API em vários ambientes.", "category": "guideline", "icon": "edit-document-outline", "order": 174, "outcomes": [ "Melhor compreensão dos princípios das estruturas de automatização de testes", "Abordagem normalizada utilizando estruturas de automatização de testes", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Implementar estruturas de automatização de testes que apoiem os testes de contrato, os testes de integração e os testes de ponta a ponta." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "vendor-management-best-practices", "slug": "resources/vendor-management-best-practices", "title": "Boas práticas de gestão de fornecedores", "description": "Estrutura para avaliar e gerir fornecedores externos de API e integrações de terceiros com base no risco, desempenho e conformidade.", "category": "guideline", "icon": "edit-document-outline", "order": 178, "outcomes": [ "Melhor compreensão dos princípios das boas práticas de gestão de fornecedores", "Abordagem normalizada utilizando as boas práticas de gestão de fornecedores", "Melhoria da implementação das práticas de API relacionadas" ], "steps": [ "Estabelecer processos de gestão de fornecedores para avaliar, integrar e monitorizar fornecedores de API de terceiros.", "Definir critérios para avaliar as APIs dos fornecedores, incluindo fiabilidade, segurança e conformidade." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "integration-style-selection-guide", "slug": "resources/integration-style-selection-guide", "title": "Guia de seleção do estilo de implementação", "description": "Orientação para escolher entre API, evento, ficheiro, stream, produto de dados, integração direta ou estilos de implementação híbridos com base nos requisitos e restrições.", "category": "guideline", "icon": "edit-document-outline", "order": 180, "outcomes": [ "Estilo de implementação de integração justificado", "Compromissos documentados entre opções de estilo de implementação", "Estilo selecionado rastreável aos requisitos dos utilizadores, da plataforma, dos dados e da operação" ], "steps": [ "Compare estilos de implementação viáveis face a necessidades de latência, volume, acoplamento, propriedade dos dados, atualidade, governação e operabilidade.", "Identifique quando API, evento, ficheiro, stream, produto de dados, integração direta ou abordagens híbridas se ajustam ao caso de utilização.", "Documente restrições, riscos e dependências da plataforma para o estilo de implementação selecionado.", "Registe por que motivo as alternativas rejeitadas não foram selecionadas." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "process-workflow-design-guide", "slug": "resources/process-workflow-design-guide", "title": "Guia de desenho do processo e workflow", "description": "Orientação para modelar passos do processo, papéis, passagens de responsabilidade, pontos de decisão, estados, entradas, saídas e exceções que moldam um workflow de automatização.", "category": "guideline", "icon": "edit-document-outline", "order": 181, "outcomes": [ "Desenho claro do workflow de automatização", "Passos do processo e passagens de responsabilidade documentados antes da implementação", "Estados do workflow, entradas, saídas e caminhos de exceção compreendidos" ], "steps": [ "Mapeie o fluxo do processo atual e alvo, incluindo responsabilidades humanas e dos sistemas.", "Identifique gatilhos do workflow, estados, decisões, entradas de dados, saídas e critérios de conclusão.", "Documente passagens de responsabilidade entre utilizadores, sistemas, operações e papéis de suporte.", "Confirme que passos devem ser automatizados e quais exigem julgamento humano." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "decision-business-rules-guide", "slug": "resources/decision-business-rules-guide", "title": "Guia de decisões e regras de negócio", "description": "Orientação para captar regras, limiares, decisões, aprovações, verificações de elegibilidade e responsabilidade pelas regras no desenho de automatizações.", "category": "guideline", "icon": "edit-document-outline", "order": 182, "outcomes": [ "Decisões e regras de negócio explícitas", "Regras e limiares documentados com responsáveis", "Decisões da automatização rastreáveis a políticas, processos ou intenção de negócio" ], "steps": [ "Liste as decisões que a automatização deve tomar ou apoiar.", "Documente condições das regras, limiares, exceções, aprovações e pontos de escalamento.", "Identifique responsáveis pelas regras e governação de alterações para cada área de decisão." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "automation-trigger-handoff-exception-guide", "slug": "resources/automation-trigger-handoff-exception-guide", "title": "Guia de gatilhos, passagens de responsabilidade e exceções da automatização", "description": "Orientação para definir gatilhos de automatização, passagens para intervenção humana, tratamento de exceções, tentativas repetidas, ações compensatórias e caminhos de escalamento de suporte.", "category": "guideline", "icon": "edit-document-outline", "order": 183, "outcomes": [ "Gatilhos de automatização e caminhos de exceção definidos", "Passagens para intervenção humana e escalamentos de suporte estão explícitos", "Exceções, tentativas repetidas e ações compensatórias desenhadas antes da entrega" ], "steps": [ "Defina os eventos, calendários, ações de utilizadores ou estados de sistema que acionam a automatização.", "Mapeie passagens da automatização para utilizadores, operadores ou equipas de suporte.", "Documente exceções, regras de nova tentativa, comportamento de timeout e caminhos alternativos.", "Defina alertas e limiares de escalamento para resultados de automatização falhados ou ambíguos." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "automation-testing-guide", "slug": "resources/automation-testing-guide", "title": "Guia de testes de automatização", "description": "Orientação para testar workflows automatizados, decisões, integrações, exceções, comportamento de rollback, supervisão e impacto nos utilizadores antes da publicação.", "category": "guideline", "icon": "edit-document-outline", "order": 184, "outcomes": [ "Comportamento da automatização validado", "Testes de workflow, regras, exceções e integração definidos", "Confiança na publicação para caminhos automatizados e assistidos por pessoas" ], "steps": [ "Crie testes para caminhos esperados, casos-limite, exceções, tentativas repetidas e passagens de responsabilidade.", "Valide regras de negócio e resultados de decisão com dados representativos.", "Teste rollback, recuperação, observabilidade e caminhos de intervenção manual.", "Inclua utilizadores e operadores em testes de aceitação quando a automatização altera práticas de trabalho." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "automation-operational-ownership-guide", "slug": "resources/automation-operational-ownership-guide", "title": "Guia de responsabilidade operacional da automatização", "description": "Orientação para definir responsabilidade, runbooks, supervisão, suporte, monitorização, controlo de alterações e responsabilidades de melhoria contínua para automatizações.", "category": "guideline", "icon": "edit-document-outline", "order": 185, "outcomes": [ "Modelo operacional claro para a automatização", "Responsabilidades de propriedade, suporte e escalamento atribuídas", "Práticas de monitorização e alteração prontas para operação em produção" ], "steps": [ "Defina responsáveis de negócio, técnicos e operacionais pela automatização.", "Documente runbooks, caminhos de suporte, sinais de monitorização, expectativas de serviço e regras de escalamento.", "Defina controlo de alterações e práticas de revisão para atualizações de workflow, plataforma e regras." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "automation-rollback-supervision-guide", "slug": "resources/automation-rollback-supervision-guide", "title": "Guia de rollback e supervisão da automatização", "description": "Orientação para desenhar caminhos de rollback, pausa, substituição manual, monitorização, supervisão e recuperação para automatizações.", "category": "guideline", "icon": "edit-document-outline", "order": 186, "outcomes": [ "Caminhos controlados de recuperação da automatização", "Comportamento de rollback, pausa e substituição manual documentado", "Necessidades de supervisão e responsabilidades de recuperação definidas" ], "steps": [ "Identifique ações que devem poder ser revertidas, pausadas ou substituídas manualmente.", "Defina procedimentos de rollback, compensação e recuperação para resultados de automatização falhados ou incorretos.", "Documente limiares de supervisão, alertas e pontos de decisão manual.", "Valide os procedimentos de recuperação antes da publicação." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "automation-readiness-checklist", "slug": "resources/automation-readiness-checklist", "title": "Checklist de prontidão da automatização", "description": "Uma checklist para validar workflow de automatização, controlos, risco, conformidade, supervisão humana, evidências de teste, rollback, operações e prontidão para publicação.", "category": "checklist", "icon": "check-box-outline", "order": 187, "outcomes": [ "Prontidão da automatização documentada", "Lacunas de prontidão conhecidas e mitigações antes da publicação", "Evidências para qualidade, risco, conformidade, supervisão e aprovação operacional" ], "steps": [ "Reveja desenho do workflow, regras de negócio, controlos, acesso, tratamento de dados e caminhos de exceção.", "Verifique evidências de teste, procedimentos de rollback, modelo de supervisão e prontidão do suporte.", "Confirme responsabilidade, runbooks, monitorização, controlos de alteração e aprovação de publicação.", "Registe lacunas por resolver, decisões e riscos aceites antes da publicação." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true }, { "id": "automation-rollout-enablement-guide", "slug": "resources/automation-rollout-enablement-guide", "title": "Guia de rollout e enablement da automatização", "description": "Orientação para implementar automatizações com comunicação aos utilizadores, onboarding, instruções operacionais, caminhos de suporte, gestão da mudança e ciclos de feedback.", "category": "guideline", "icon": "edit-document-outline", "order": 188, "outcomes": [ "Utilizadores e operadores da automatização preparados", "Comunicação de rollout, onboarding e caminhos de suporte preparados", "Utilizadores e operadores compreendem como o trabalho muda após a publicação da automatização" ], "steps": [ "Defina públicos do rollout, calendário, canais de comunicação e necessidades de formação.", "Publique instruções operacionais, caminhos de suporte, orientação para exceções e contactos de escalamento.", "Planeie suporte de transição para utilizadores, operadores e responsáveis pelo processo.", "Recolha feedback após o rollout e alimente o backlog com melhorias." ], "canvasId": null, "sourcePath": null, "sourceUrl": null, "contentMarkdown": null, "draft": true } ], "criteria": [ { "id": "metrics-feedback-available", "title": "Sinais de mercado relevantes, feedback ou conhecimento operacional estão disponíveis para orientar esta oportunidade de capacidade.", "description": "Relevant market signals, feedback, or operational insights are available to guide this API opportunity.", "category": "" }, { "id": "business-goals-defined", "title": "Os objetivos de negócio estão definidos.", "description": "Business goals are defined.", "category": "" }, { "id": "market-research-done", "title": "A investigação de mercado identifica oportunidades de capacidade.", "description": "Market research identifies API opportunities.", "category": "" }, { "id": "stakeholder-approval", "title": "As partes interessadas relevantes concordam que vale a pena explorar e priorizar esta oportunidade de capacidade.", "description": "Relevant stakeholders agree this API opportunity is worth exploring and prioritizing.", "category": "" }, { "id": "api-opportunity-documented", "title": "A oportunidade de capacidade está identificada e documentada.", "description": "Individual API opportunities are identified and documented.", "category": "" }, { "id": "api-reusability", "title": "A capacidade responde a uma necessidade clara de negócio e é reutilizável pelos utilizadores previstos.", "description": "The API meets a clear business need and is reusable for multiple API consumers.", "category": "" }, { "id": "hide-backend-discrepancies", "title": "A interface selecionada fornece uma abstração adequada aos utilizadores.", "description": "The API is intended to shield consumers from backend complexity and inconsistencies.", "category": "" }, { "id": "value-prop-validated", "title": "A proposta de valor da capacidade foi validada com partes interessadas de negócio e utilizadores.", "description": "The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders.", "category": "" }, { "id": "consumer-segments-identified", "title": "Os segmentos de utilizadores estão identificados.", "description": "API consumer segments (internal and external) are identified.", "category": "" }, { "id": "api-roadmap-defined", "title": "Está definido um roadmap de implementação de alto nível.", "description": "High-level roadmaps for API development are established.", "category": "" }, { "id": "architecture-patterns-validated", "title": "A arquitetura, plataforma e estilo de implementação escolhidos foram validados com as partes interessadas relevantes de arquitetura, segurança e plataforma.", "description": "The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders.", "category": "" }, { "id": "design-reflects-business-value", "title": "O desenho da interface e as capacidades expostas são rastreáveis ao valor de negócio e às necessidades dos utilizadores.", "description": "The API design and exposed capabilities clearly trace back to business value and user needs.", "category": "" }, { "id": "api-consistency", "title": "O desenho da interface segue os standards e convenções de desenho acordados.", "description": "The API design follows our shared API product and design conventions.", "category": "" }, { "id": "api-contract-tested", "title": "O contrato de interface foi validado e testado face aos requisitos funcionais e não funcionais.", "description": "The API contract is tested and meets functional and non-functional requirements.", "category": "" }, { "id": "automation-workflow-validated", "title": "O workflow, as regras, as integrações e os contratos de interface relevantes foram validados e testados.", "description": "The workflow, rules, integrations, and relevant interface contracts have been validated and tested.", "category": "" }, { "id": "api-description-available", "title": "A interface e as suas capacidades estão documentadas de forma suficientemente clara para revisão, auditoria e onboarding.", "description": "The API and its exposed capabilities are described clearly enough for review, audit, and onboarding.", "category": "" }, { "id": "audit-passed", "title": "A solução passa as verificações de qualidade, segurança, conformidade e prontidão.", "description": "The API passes compliance, security, and audit checks.", "category": "" }, { "id": "audit-reports-shared", "title": "As conclusões da auditoria e as decisões de correção são partilhadas com as partes interessadas relevantes.", "description": "Audit findings and remediation decisions are shared with the relevant stakeholders.", "category": "" }, { "id": "api-ready-for-publishing", "title": "A capacidade está pronta para ser publicada ou disponibilizada através do mecanismo de entrega selecionado.", "description": "The API is ready to be deployed and exposed through the intended gateways and environments.", "category": "" }, { "id": "api-documentation-ready", "title": "A documentação orientada para os utilizadores e os materiais de onboarding estão prontos.", "description": "Consumer-facing API documentation is complete enough for publishing and onboarding.", "category": "" }, { "id": "consumer-support-ready", "title": "Os processos de onboarding, suporte e comunicação para utilizadores estão prontos.", "description": "Registration, support, and communication processes are ready for API consumers.", "category": "" }, { "id": "legal-compliance-clear", "title": "Os requisitos legais, de privacidade e de conformidade para publicação ou disponibilização estão definidos e compreendidos.", "description": "Legal, privacy, and compliance requirements for publishing are defined and understood.", "category": "" } ] } } }