A área de governança precisa cruzar o anseio e desejos dos outros setores da empresa, com o objetivo de construir uma ponte entre o momento atual da empresa com o que pode acabar sendo uma futura estratégia de governança de API.
É clichê, mas resumindo fica assim: a área de governança busca alinhar a estratégia com a execução.
😒: Todo novo framework da moda tem essa frase. Como é possível esse alinhamento com a governança?
O monitoramento do desempenho passado é útil na avaliação de opções no momento presente, para determinar metas, políticas e ações futuras (direção). 😎
Aqueles que não conhecem a história estão fadados a repeti-la.
-- Edmund Burke
Como vai conseguir monitorar o passado se não sabe o que monitorar? No catalogo de API precisa existir no mínimo 4 informações, sendo elas o recurso, a estrutura, a capacidade e a sensibilidade. Logo ter um catalogo de API é o primeiro passo para o sucesso!
O contrato da API: o primeiro e mais importante passo
Sem duvidas aqui é o ponto mais importante e mais complicado de ser feito, mas quando bem feito só temos ganhos. Para entender mais o motivo de começar com o contrato leia esse artigo:
Em um programa de desenvolvimento de API a primeira etapa é justamente a construção de um contrato. Com um contrato bem feito conseguimos automatizar rotinas, melhorar a experiência do desenvolvedor, permitir a independência dos times, acelerar a entrega das APIs para o mercado, melhora o entendimento das suas APIs, facilitar a rotina de testes 👻, gerar SDKs tanto para o cliente quanto para o servidor (ação automatizada é claro), possibilidade de ativar e desativar suas APIs e como não podia deixar de ser, monitorar o passado!
😒: o mundo real não é assim, ninguém para para criar contratos. O que o gestor quer é código em produção. Contrato, só se for contrato com um cliente pagante.
É uma visão bem comum, se você for direto para a criação de sua API, não haverá retorno ao design. É como construir uma casa e depois procurar um arquiteto para elaborar planos. Isso não faz nenhum sentido. 😎
No entanto, as equipes de software frequentemente fazem escolhas semelhantes. Eles podem gerar uma especificação de API a partir do código, o que parece eficiente. Infelizmente, quando você criou uma API no código, perdeu muitas das vantagens da abordagem do design primeiro. Quando o design da sua API existe antes da implementação, você pode obter feedback antecipado, conectar sua API às ferramentas desde o início e colaborar entre departamentos e funções. 😎
Colocar ordem no caos é uma tarefa árdua, ou exigir que desenvolvedores sigam um método que não seja o eXtreme Go Horse (XGH). Mas é necessário dar o primeiro passo. Assim também é implantar um programa de API, tenha em mente qual resultado deseja obter, e não foque no tamanho do percurso.
Suba o primeiro degrau com fé. Não é necessário que você veja toda a escada. Apenas dê o primeiro passo.
-- Martin Luther King
Você sabe quem usará sua API? Mesmo para um projeto interno, é provável que você tenha vários consumidores. Uma especificação de API permite que você compartilhe detalhes sobre como a API funcionará. Você pode enviar o documento de especificação em si ou usar ferramentas para criar um protótipo de sua API ou documentação. Você pode gerar servidores simulados com base em suas especificações, conforme descrito em outra seção, e fazer com que seus consumidores façam chamadas ao vivo.
Sua colaboração também pode ir além das equipes técnicas. Você pode obter ótimas informações sobre produtos, marketing, parcerias e muitas outras áreas da sua organização.
🙋♂️: Eu ouvi um amém irmãos?! 🙌🙌
O software raramente é construído inteiramente por desenvolvedores. Existem partes interessadas em toda a organização. E embora muitos desenvolvedores possam ter muita atenção ao produto, eles nem sempre têm a visibilidade da imagem completa. Se sua organização possui um grupo de produtos, é nesse ponto que a voz do cliente é mais ouvida. Envolva qualquer pessoa que entenda como uma API será usada nas discussões ao criar a API.
Quando você entender como o software será usado, poderá projetá-lo melhor. O maior erro no design da API é tomar decisões com base em como o sistema funciona, e não no que os consumidores precisam oferecer suporte. Para projetar casos de uso, você precisa conversar com os consumidores ou, pelo menos, incluir aqueles que os conhecem melhor.
Uma sugestão de ferramenta que faz muito bem esse papel e para melhorar seu dia é gratuita Stoplight Studio
The modern editor for API Design and Technical Writing.
Stoplight Studio
Studio is Stoplight's next generation application for API design, modeling, and technical writing. A primary goal of Studio is to enrich, not replace, your existing workflows. When running locally it works fully offline, with folders and files on your computer just like your favorite IDE. When running in the browser, the web-native Git support allows you to effortlessly work with your existing repositories safely and efficiently.
Studio comes with full support for the OpenAPI versions 2 and 3 specification formats for all functionality. That means full validation, mocking, and modeling support for both versions of the OpenAPI specification.
Graphical API Design
Form-based designing means you don't need to be an OpenAPI expert to get started. Studio has a "write" (code) mode with full OpenAPI autocomplete…
🧙: Já temos o contrato e o mock da API, que tal criar um código de API para rodar no servidor usando 1 linha de comando? Te apresento meu amigo, Openapi Generator
OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)
⚠️ If the OpenAPI spec, templates or any input (e.g. options, environment variables) is obtained from an untrusted source or environment, please make sure you've reviewed these inputs before using OpenAPI Generator to generate the API client, server stub or documentation to avoid potential security issues (e.g. code injection). For security vulnerabilities, please contact team@openapitools.org. ⚠️
‼️ Both "OpenAPI Tools" (https://OpenAPITools.org - the parent organization of OpenAPI Generator) and "OpenAPI Generator" are not…
![[Série] Governança de API: Contrato da API](https://media2.dev.to/dynamic/image/width=1000,height=420,fit=cover,gravity=auto,format=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fi%2Fnjha8qnx4m8gj5mcf91z.png)
![[Série] Governança de API: Centralização](https://media2.dev.to/dynamic/image/width=1000,height=420,fit=cover,gravity=auto,format=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fi%2Fq7tvz6zyomqferq1bavi.png)
![[Série] Governança de API](https://media2.dev.to/dynamic/image/width=1000,height=420,fit=cover,gravity=auto,format=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fi%2F6fqenxqya02ocasvcyv7.PNG)