DEV Community

loading...
Cover image for [Série] Governança de API: Contrato da API
DEVz Wiz

[Série] Governança de API: Contrato da API

juscelior profile image Pode me chamar de Juscélio Reis Updated on ・6 min read

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!

Ciclo de vida da API

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

GitHub logo stoplightio / studio

The modern editor for API Design and Technical Writing.

Stoplight Studio

Buy us a tree

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.

Features

Full Support for OpenAPI v2 and v3

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.

Studio loves Swagger + OpenAPI

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, and a "read" mode for visualizing HTTP operations and models.

Graphical Design for OpenAPI

To find out more about…

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.

GitHub logo stoplightio / prism

Turn any OpenAPI2/3 and Postman Collection file into an API server with mocking, transformations and validations.

Prism - API Mock Servers and Contract Testing

CircleCI NPM Downloads Buy us a tree

Prism is a set of packages for API mocking and contract testing with OpenAPI v2 (formerly known as Swagger) and OpenAPI v3.x.

  • Mock Servers: Life-like mock servers from any API Specification Document.
  • Validation Proxy: Contract Testing for API Consumers and Developers.
  • Comprehensive API Specification Support: OpenAPI 3.0, OpenAPI 2.0 (FKA Swagger) and Postman Collections support.

Demo of Prism Mock Server being called with curl from the CLI

Note: This branch refers to Prism 3.x, which is the current version most likely you will use. If you're looking for the 2.x version, look at the 2.x branch

Overview

🧰 Installation and Usage

Installation

Prism requires NodeJS >= 12 to properly work.

npm install -g @stoplight/prism-cli
# OR
yarn global add @stoplight/prism-cli
Enter fullscreen mode Exit fullscreen mode

For more installation options, see our installation documentation.

Mocking

prism mock https://raw.githack.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml
Enter fullscreen mode Exit fullscreen mode

Validation Proxy

prism proxy examples/petstore.oas2.yaml https://petstore.swagger.io/v2
Enter fullscreen mode Exit fullscreen mode

📖 Documentation and Community

🚧

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

GitHub logo OpenAPITools / openapi-generator

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

OpenAPI Generator

Stable releaases in Maven Central Apache 2.0 License Open Collective backers Join the Slack chat room Follow OpenAPI Generator Twitter account to get the latest update

Master (5.1.0) Build Status Integration Test2 Run Status Windows Test JDK11 Build Bitrise GitHub Workflow Status (branch)

6.0.x (6.0.x) Build Status Integration Test2 Run Status Windows Test JDK11 Build Bitrise

If you would like to contribute, please refer to guidelines and a list of open tasks.

‼️ To migrate from Swagger Codegen to OpenAPI Generator, please refer to the migration guide ‼️

📔 For more information, please refer to the Wiki page and FAQ 📔

📔 The eBook A Beginner's Guide to Code Generation for REST APIs is a good starting point for beginners 📔

⚠️ 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…

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


Discussion (0)

Forem Open with the Forem app