Recapitulando:

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!

Para recapitular pode ir direto na fonte:

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

Para gerar um mock desse contrato criado pelo Stoplight Studio é possível usar Prism na linha de comando e entregar esse mock para o dev front-end.

🧙: 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

😒: Da onde ele veio?

🧙: Do github

😒: O que ele faz?

🧙: Gera SDK, código do desenvolvedor e documenta tudo. O melhor amigo do Dev SAGAZ.

CLIENT generators

• ada
• android
• apex
• bash
• c
• clojure
• cpp-qt5-client
• cpp-restsdk
• cpp-tizen
• cpp-ue4 (beta)
• csharp
• csharp-dotnet2 (deprecated)
• csharp-netcore
• dart
• dart-dio
• dart-jaguar
• eiffel
• elixir
• elm
• erlang-client
• erlang-proper
• flash
• go
• go-experimental (experimental)
• groovy
• haskell-http-client
• java
• javascript
• javascript-apollo (beta)
• javascript-closure-angular
• javascript-flowtyped
• jaxrs-cxf-client
• jmeter
• k6 (beta)
• kotlin
• lua (beta)
• nim (beta)
• objc
• ocaml
• perl
• php
• powershell (beta)
• python
• python-experimental (experimental)
• r
• ruby
• rust
• scala-akka
• scala-gatling
• scala-httpclient-deprecated (deprecated)
• scala-sttp (beta)
• scalaz
• swift4-deprecated (deprecated)
• swift5 (beta)
• typescript (experimental)
• typescript-angular
• typescript-angularjs-deprecated (deprecated)
• typescript-aurelia
• typescript-axios
• typescript-fetch
• typescript-inversify
• typescript-jquery
• typescript-node
• typescript-redux-query
• typescript-rxjs

SERVER generators

• ada-server
• aspnetcore
• cpp-pistache-server
• cpp-qt5-qhttpengine-server
• cpp-restbed-server
• csharp-nancyfx
• erlang-server
• fsharp-functions (beta)
• fsharp-giraffe-server (beta)
• go-gin-server
• go-server
• graphql-nodejs-express-server
• haskell
• java-inflector
• java-msf4j
• java-pkmst
• java-play-framework
• java-undertow-server
• java-vertx
• java-vertx-web (beta)
• jaxrs-cxf
• jaxrs-cxf-cdi
• jaxrs-cxf-extended
• jaxrs-jersey
• jaxrs-resteasy
• jaxrs-resteasy-eap
• jaxrs-spec
• kotlin-server
• kotlin-spring
• kotlin-vertx (beta)
• nodejs-express-server (beta)
• php-laravel
• php-lumen
• php-silex-deprecated (deprecated)
• php-slim-deprecated (deprecated)
• php-slim4
• php-symfony
• php-ze-ph
• python-aiohttp
• python-blueplanet
• python-flask
• ruby-on-rails
• ruby-sinatra
• rust-server
• scala-akka-http-server (beta)
• scala-finch
• scala-lagom-server
• scala-play-server
• scalatra
• spring

DOCUMENTATION generators

• asciidoc
• cwiki
• dynamic-html
• html
• html2
• markdown (beta)
• openapi
• openapi-yaml
• plantuml (beta)

SCHEMA generators

• avro-schema (beta)
• mysql-schema

CONFIG generators

• apache2
• graphql-schema
• protobuf-schema (beta)

Que tal dar o primeiro passo? Se esta na duvida olha essa musica que fizeram para quem não quis arriscar:

1. Introduçao
2. Centralização
3. Contrato da API
4. Diretrizes de estilo
5. Reutilização
6. Automação
7. Versionamento
8. Política de descontinuação
9. Rastreamento / Observabilidade
10. Descoberta de API

Referencial

• Adaptive Strategy
• Launching a Scalable API Program with OpenAPI: Optimize Your API Workflow with OpenAPI & Swagger
• What is API Design?
• eXtreme Go Horse (XGH)

---