API #02: Design

ago 08, 2024

O que é design de API?

Design de API envolve em planejar, preparar e desenvolver cuidadosamente interfaces de programação (APIs) para expor os dados e a funcionalidade do sistema aos consumidores. As APIs permitem a comunicação entre sistemas e são essenciais para as organizações porque adicionam novos recursos aos seus produtos, operações, estratégias de parceria e muito mais.

Um design de API eficaz é aquele que possui respostas satisfatórias às seguintes dúvidas de um desenvolvedor:

Por que a API está sendo desenvolvida?
Qual seria o resultado em relação ao impacto e ao resultado do sistema?
Como a API será projetada para atender aos requisitos?
Qual será a estrutura dos nossos endpoints?
Como documentaremos nossos endpoints?

Projetar uma API envolve o uso eficiente de serviços remotos para resolver problemas, de modo que os requisitos funcionais e não funcionais do cliente sejam atendidas de forma satisfatória. Uma API deve estar bem alinhada para negócios para os quais está sendo desenvolvida.

Por que um bom design é importante?

Uma API é um produto semelhante a um site ou um aplicativo de software. Qual seria a nossa reação se interagíssemos com um produto mal desenhado? Provavelmente mudaríamos instantaneamente para outro aplicativo com um design melhor e que fornecesse a mesma funcionalidade. O mesmo pensamento se aplica às APIs como produtos. É importante projetar uma API seguindo todos os requisitos do usuário final.

A análise de requisitos deve ser realizada antes do desenvolvimento da API. Esta análise é realizada durante a fase de design. É possível atualizar o design obtendo feedback interno ou de clientes.

Vejamos como isso ocorre no ciclo de vida de um design abaixo.

Ciclo de vida de um design de API…

Lembre-se de que os desenvolvedores são os clientes que usarão sua API. Em cada ciclo de vida do produto, a primeira fase é projetá-lo conforme os requisitos funcionais e não funcionais. O mesmo acontece com APIs. Como qualquer outro produto ou aplicativo, os desenvolvedores esperam que as APIs sejam simples, úteis e fáceis de adotar. Portanto, o desenvolvimento da API segue o mesmo ciclo de vida de outros produtos, conforme mostrado abaixo:

A abordagem design-first…

A abordagem code first é a forma mais comum de criar APIs. Dessa forma, o desenvolvimento do código começa depois que os requisitos de negócios são definidos e a documentação é eventualmente gerada a partir do código.

Em comparação, o design first é quando você cria um contrato ou documento para definir a API antes de começar a escrever o código.

A abordagem code first pode ser útil nos seguintes cenários:

Entrega rápida de um produto
Uma API apenas para uso interno
Pouca ou nenhuma documentação necessária pela simplicidade da API

Faria muito pouco sentido começar a construir uma casa sem primeiro ter um projeto de arquitetura para elaborar os planos e o projeto da casa. Da mesma forma, é mais claro que as APIs comecem com uma abordagem que prioriza o design.

Geralmente, as especificações podem mudar dependendo dos usuários finais da API, o que pode alterar a sua estrutura.

Com a abordagem design first, podemos obter feedback antecipado que pode nos salvar de erros futuros, porque o design de uma API pode ser atualizado muito mais rápido do que seu código.

💡 Se quiser ter mais informações sobre técnicas e estilos de documentação de API, veja este post sobre Documentação de API no modelo de arquitetura REST.

Considerações para um design de API…

A imagem a seguir mostra os pontos-chave para um melhor design de API:

Identificação dos usuários: identifique os usuários potenciais em termos de seu relacionamento com o negócio (parceiros, clientes ou desenvolvedores externos) para o qual a API está sendo desenvolvida. Esta identificação definirá o nível de acesso e tipo de autenticação a ser implementada na API. Os tipos de usuários também ajudarão a identificar e implementar o estilo arquitetura correto, como, por exemplo, REST, gRPC entre outros.
Identificação dos problemas: identifique quais problemas você quer resolver com sua API em termos de relacionamento comercial, necessidades críticas e agregação de valor. Também é necessário identificar as métricas que você irá acompanhar para posteriormente melhorar após o uso da API. Essas métricas incluem receita, velocidade de integração de tarefas, custos e entre outras.
Identificação das respostas (responses): É importante identificar as respostas (responses) de sucessos ou erros às diferentes chamadas de sua API para os desenvolvedores poderem entender o tipo e o motivo das respostas recebidas do servidor. O tratamento de exceções e erros deve ser implementado com endpoints bem definidos.
Identificação de casos de uso: A implementação de casos de uso deve ser realizada para que o fator de testabilidade seja avaliado e os desenvolvedores compreendam a eficácia da API projetada em termos de desafios. Durante o projeto, deve-se analisar o desempenho da API testando diferentes situações de uso possíveis**.**
Escalabilidade: A API deve ser escalável para lidar com as crescentes demandas dos clientes. Portanto, o design da API deve considerar a escalabilidade como um fator importante para evitar modificações fundamentais no futuro.
Documentação: A API deve ter uma documentação para os desenvolvedores poderem compreender facilmente a integração, os comportamentos, as estruturas e os parâmetros a serem definidos durante o uso da API.

Requisitos de uma API

Precisamos definir os requisitos funcionais e não funcionais de nossas APIs. Dê uma olhada em ambos os tipos de requisitos abaixo:

Os requisitos funcionais: definem a função final desejada em um sistema e seus parâmetros de entrada exigidos. Por exemplo, um serviço de streaming de vídeo determina a capacidade de postar comentários em um vídeo. Isso é um requisito funcional porque tem um objetivo final e parâmetros bem definidos.
Os requisitos não funcionais: definem o desempenho e a qualidade dos serviços que a API fornece. Continuando com o exemplo de streaming de vídeo acima, a capacidade de uma API responder rapidamente ao usuário (baixa latência) ou vários usuários postando comentários simultaneamente (escalabilidade) são formas de requisitos não funcionais. Outros requisitos não funcionais incluem disponibilidade, confiabilidade, consistência entre outros

Características de um bom design de API…

Existem muitas características desejáveis em um bom design de API. Listarei alguns deles para ter em mente quando estudarmos uma API ou projetarmos uma nova. No entanto, a evolução da tecnologia muitas vezes afeta como as APIs são especificadas e novas características podem ser adicionadas no futuro.

Veja algumas características importante abaixo:

Separação entre especificação de API e sua implementação

Inclui separação entre a especificação e sua implementação, ou seja, o comportamento com os detalhes estruturais internos. Designs limpos permitem melhorias e mudanças iterativas na implementação da API.

Concorrência

Quantidade de chamadas de API que podem estar ativas simultaneamente em um período especificado é útil para garantir que os recursos computacionais estejam disponíveis para todos os usuários.

Rate-limiting

Estratégia para limitar o acesso à API num determinado prazo. Evita sobrecarregar a API com um ataque violento de solicitações.

Segurança

Mecanismos de segurança bem definidos para protocolos de autenticação e autorização que definirão quem pode acessar a API e quais partes da API que um determinado usuário pode acessar.

Avisos de erro e tratamento de exceção

Permite o tratamento eficaz de erros para evitar a frustração do consumidor final. Reduz os esforços de depuração para desenvolvedores.

Simples, mas abrangente e coesa

A API deve ser o mais concisa possível, mas cumprir seus objetivos.

Tolerância a falhas

As falhas são inevitáveis, mas uma API bem projetada pode se tornar tolerante a falhas usando mecanismos que garantam a operação contínua da API, mesmo que alguns componentes funcionem mal.