Desenhe primeiro sua interface de API, antes de desenvolver
Projetar interfaces de API na maioria das vezes é a melhor forma para validar o contrato e funcionamento da API, antes de começar a programar.
Vamos considerar que você vai começar a desenvolver uma API hoje, e ai vem a primeira pergunta “Por onde começar”? A resposta é “desenhando” sua interface de API. Esse é o princípio do Design First de API. Antes de começar a desenvolver códigos para seu back-end, crie a especificação da sua interface de API.
É muito melhor errar e corrigir aqui do que nos próximos passos!
Vem comigo, que eu te conto mais a respeito a seguir.
Identifique os resources
O conceito fundamental em qualquer API RESTful é o recurso. Um recurso é um objeto com um tipo, dados associados, relacionamentos com outros recursos e um conjunto de métodos que operam nele. É semelhante a uma instância de objeto em uma linguagem de programação orientada a objetos, com a importante diferença de que apenas alguns métodos padrão são definidos para o recurso (correspondendo aos métodos padrão HTTP GET, POST, PUT, DELETE, …), enquanto uma instância de objeto geralmente tem outros métodos.
Os resources podem ser agrupados em collections. Cada collection é homogênea para que contenha apenas um tipo de resource. Os resources também podem existir fora de qualquer collection. Nesse caso, nos referimos a esses recursos como singleton resource. As collections também são resources.
As coleções podem existir globalmente, no nível superior de uma API, mas também estão contidas em um único recurso. Neste caso, nos referimos a essas collections como subcoleções. As subcollections geralmente são usadas para expressar algum tipo de relacionamento “contido em”. Entramos em mais detalhes sobre isso em Relacionamentos.
O diagrama abaixo ilustra os principais conceitos em uma API RESTful:
Chamamos as informações que descrevem os tipos de recursos disponíveis, seu comportamento e relacionamentos de modelo de recursos de uma API. O modelo de recurso pode ser visualizado como o mapeamento RESTful do modelo de dados do aplicativo.
Design-first
Na maioria das vezes, faz todo sentido validar a API em etapas e construir a solução junto com o cliente ou personas externas. Isso faz com que se valide a ideia, crie documentação, teste e melhore antes de começar a escrever o código da API.
As primeiras vantagens óbvias são que o código já tem um esqueleto e que algumas ferramentas podem fornecer código clientes automaticamente.
Na Neoway, utilizamos o OpenAPI Specification para descrever o comportamento da API. Essa especificação é um padrão disseminado no mercado, usado por muitos serviços e softwares, podendo facilmente ser importado e ter a documentação suficiente para conhecer o contrato de API e iniciar a integração.
Endpoints e Verbos
Os endpoints e os verbos são os endereços para acessar alguma funcionalidade da API, são as formas de solicitar alguma coisa, algo como: “Dá os dados da minha conta aí”, resultaria em um GET em `/accounts/me`. O conjunto de endpoints, formam o produto de API, como nesse exemplo, um micro serviço de pedidos de compras:
Schemas
Os schemas representam os objetos de domínio ou tipos de abstrações para objetos, utilizados para interagir com a API pelo request ou response.
Como neste exemplo, a abstração de uma Conta e uma Ordem de Compra:
Com o schema definido no documento OpenAPI, a integração e testes se tornam mais fáceis por conta do objeto schema dar clareza de como será o retorno da API. Imagina que você pode enviar o OpenAPI para outros desenvolvedores validar se o objeto tem todas as informações necessários para o uso.
Especificação perto do código
Tá, digamos que escrevemos o documento de especificação da API. Onde colocamos esse documento?
A sugestão seria colocar o documento OpenAPI dentro do próprio projeto do código da API.
O ponto positivo de ter a documentação via código, é que podemos fazer commit desses arquivos em um repositório e ter controle de versão sobre eles. Assim, colocamos as pipelines de CI/CD para rodar🤘
As descrições da OpenAPI não são apenas um artefato de documentação: são arquivos de origem de primeira classe que podem conduzir um grande número de processos automatizados, incluindo geração de boilerplate, teste de unidade e renderização da documentação.
Como tal, a descrição do OpenAPI deve ser mantida no seu repositório, de fato, deve estar entre os primeiros arquivos a serem confirmados. A partir daí, eles devem participar dos processos de Integração Contínua.
Para mais informações sobre como configurar a pipeline leia esse artigo:
Referências
https://oai.github.io/Documentation/best-practices.html
https://developers.redhat.com/blog/2019/02/25/full-api-lifecycle-management-a-primer
https://rapidapi.com/blog/api-lifecycle-management
https://restful-api-design.readthedocs.io/en/latest/resources.html
Curtiu o conteúdo? Não se esqueça de deixar seus comentários, dúvidas e compartilhar esse post nas suas redes.
A Neoway desenvolve soluções de Big Data Analytics e Inteligência Artificial que geram precisão para a tomada de decisão e produtividade para os processos de marketing, compliance, prevenção contra fraudes, análises jurídicas, gestão de crédito, entre outros.
Estamos contratando: para saber mais sobre as vagas disponíveis, visite nosso perfil oficial na Gupy.
