O que é projeto de APIs?

O projeto de APIs inclui decisões sobre endpoints de APIs, formatos de solicitação e resposta, protocolos e a maneira como as APIs se comunicam com outras aplicações e consumidores. O projeto de APIs também desempenha um papel importante na governança de APIs.

A governança de APIs refere-se ao conjunto abrangente de padrões, políticas e práticas que orientam como uma organização desenvolve, implementa e utiliza suas APIs. O projeto de APIs eficaz produz APIs que aderem a essas políticas predeterminadas, com documentação robusta e atualizada que explica como a API funciona. O resultado são APIs bem projetadas, que têm melhor reutilização, escalabilidade e compatibilidade e proporcionam uma melhor experiência de usuário aos usuários finais.

Há muitos casos de uso de APIs diferentes e inúmeras abordagens para o projeto de APIs, com alguns protocolos, estilos arquitetônicos e linguagens mais adequados a tarefas ou casos de uso específicos do que outros.

À medida que o uso de APIs da web aumentou, isso levou ao desenvolvimento e uso de determinados protocolos, estilos, padrões e linguagens. Essas estruturas fornecem aos usuários um conjunto de parâmetros, ou especificações de API, que definem tipos de dados, comandos, sintaxe e muito mais aceitos. Na verdade, esses protocolos de APIs facilitam a troca de informações padronizada.

Protocolos comuns, estilos arquitetônicos e linguagens incluem:

• SOAP (simple object access protocol)
• Chamada de procedimento remoto (RPC)
• WebSocket
• REST (transferência de estado representacional)
• GraphQL

Escolher a estrutura correta para uma nova API é um aspecto importante do processo de projeto. Esses protocolos, estilos arquitetônicos e linguagens não são necessariamente melhores ou piores do que os outros. São ferramentas diferentes para tarefas diferentes.

O SOAP é uma especificação leve de protocolo de mensagens baseada em XML que permite que endpoints enviem e recebam dados por meio de diversos protocolos de comunicação, incluindo SMTP (protocolo de transferência de correio simples) e HTTP (protocolo de transferência de hipertexto). O SOAP é independente, o que permite que APIs SOAP compartilhem informações entre aplicativos ou componentes de software que rodam em ambientes diferentes ou que foram escritos em linguagens diferentes.

Em comparação com outros tipos de APIs, as APIs SOAP tendem a ser desenvolvidas de maneira mais formalizada e estruturada. As APIs SOAP existem desde a década de 1990; é um formato mais antigo e mais estabelecido, mas também mais lento do que arquiteturas mais modernas, como o REST. 

O SOAP funciona codificando dados no formato XML e não é compatível com a transferência de dados em outros formatos. Por outro lado, as APIs SOAP não exigem necessariamente HTTP para transportar mensagens, o que lhes dá mais flexibilidade na movimentação de dados. O SOAP é considerado mais seguro do que alguns outros protocolos, tornando as APIs SOAP apropriadas em sistemas que lidam com dados sensíveis.

A chamada de procedimento remoto (RPC) é um protocolo que fornece o paradigma de comunicação de alto nível usado no sistema operacional. O RPC implementa um sistema lógico de comunicação cliente-servidor projetado especificamente para dar suporte a aplicações de rede. O protocolo RPC permite que os usuários trabalhem com procedimentos remotos como se fossem locais.1 Isso os torna adequados para situações que exigem muitas interações cliente/servidor e interação cliente/servidor.

As APIs RPC podem ser divididas em XML-RPC, JSON-RPC e gRPC. XML-RPC é uma chamada de procedimento remoto que usa um formato XML específico para transferir dados. Elas são mais antigas do que as APIs de SOAP, mas simples e leves. JSON-RPC é uma chamada de procedimento remoto que usa JSON (JavaScript Object Notation) para transferir dados. Como o JSON usa estruturas de dados universais, ele pode ser usado com qualquer linguagem de programação. 

O gRPC é uma framework RPC de código aberto e de alto desempenho que foi inicialmente desenvolvida pelo Google. O gRPC usa o protocolo de rede HTTP/2 e o formato de dados Protocol Buffers e é comumente usado para conectar serviços em uma arquitetura de microsserviços.

As APIs WebSocket permitem a comunicação bidirecional entre o cliente e o servidor. Esse tipo de API não exige o estabelecimento de uma nova conexão para cada comunicação - uma vez estabelecida a conexão, ela permite a troca contínua. Isso torna as APIs Web Socket ideais para comunicação em tempo real. 

Chat ao vivo, rastreamento de localização em tempo real e transmissão de dados são excelentes casos de uso para APIs WebSocket. As APIs WebSocket também são úteis para sincronização de dados, que é a prática de manter os dados consistentes e atualizados em vários dispositivos ou sistemas, pois eles podem ser atualizados em tempo real, sem a necessidade de criar uma nova conexão cada vez que uma alteração é feita.

REST é um conjunto de princípios de arquitetura de APIs da web. As APIs REST (também conhecidas como APIs RESTful) são APIs que aderem a certas restrições arquitetônicas REST. As APIs REST usam métodos HTTP como GET, PUT, HEAD e DELETE para interagir com recursos. O REST disponibiliza dados como recursos, com cada recurso representado por um URI exclusivo. Os clientes solicitam um recurso fornecendo seu URI. APIs REST são sem estado; elas não salvam dados do cliente entre solicitações.

As APIs RESTful são populares porque são leves, flexíveis e fáceis de usar. Eles são totalmente compatíveis com o transporte de mensagens em diferentes formatos, como texto simples, HTML, YAML, XML e JSON, e também são compatíveis com o cache. Embora isso as torne úteis em uma grande variedade de contextos, algumas estações exigem uma linguagem ou protocolo mais específico para concluir uma tarefa com eficiência.

O GraphQL é uma linguagem de consulta e tempo de execução de API que o Facebook desenvolveu internamente em 2012 antes de se tornar de código aberto em 2015. O GraphQL permite que os usuários façam solicitações de APIs com apenas algumas linhas, em vez de terem que acessar endpoints complexos com muitos parâmetros. Esse recurso pode tornar mais fácil gerar e responder a consultas de APIs, especialmente as mais complexas ou específicas, que direcionam múltiplos recursos.

Considerando que a Meta desenvolveu essa linguagem de consulta para tornar suas aplicações móveis mais eficientes, faz sentido que as APIs do GraphQL sejam úteis para aplicações móveis. Ao oferecer um único ponto de entrada, as APIs do GraphQL podem reduzir os tempos de carregamento consultando dados sem precisar fazer várias solicitações ao servidor. 

Existem quatro estágios principais do processo de projeto de uma API:

• Planejar
• Desenvolvimento
• Teste
• Implemente

Todas essas etapas requerem colaboração entre os principais stakeholders de APIs. Embora algumas das etapas sejam mais adequadas para alguns stakeholders do que para outros, o projeto de APIs ainda deve ser colaborativo durante todo o processo. Isso ajuda os desenvolvedores a evitar a adição de funções extras de que o programa não precisa, acelerando o processo de desenvolvimento como um todo.

A primeira etapa de qualquer projeto é fazer com que todos concordem com o tipo de nova API que estão criando. Uma API voltada para o público destinada a interagir com os clientes em uma configuração de comércio eletrônico tem necessidades de projeto e funções diferentes de uma que se destina a ser usada internamente para um fluxo de trabalho de autenticação; é importante que todos os stakeholders entendam os casos de uso para uma API em potencial antes do início do desenvolvimento.

Entender o que uma empresa está criando (e por quê) pode dar aos desenvolvedores uma ideia melhor de como fazê-lo, incluindo quais protocolos usar. Se, por exemplo, essa API em potencial exigir comunicação em tempo real, os desenvolvedores saberão que podem usar o WebSocket ao criá-la, pois esse protocolo é adequado para essa finalidade. 

Quando os stakeholders tiverem uma visão clara do que será a API e como ela funciona, é hora de começar a construí-la. Durante o desenvolvimento de API, os desenvolvedores definem os endpoints; projetam o modelo de dados para a API; certificam-se de que a API adere às políticas de segurança de APIs e retorna códigos de status padrão para erros; se necessário, implementam mecanismos de autenticação como cabeçalhos HTTP, chaves de APIs, OAuth ou JSON Web Tokens (JWT); definem códigos de erro, mensagens e respostas.

Outra parte do processo de desenvolvimento é a documentação. Enquanto a API está sendo criada, todas as escolhas feitas devem ser capturadas em um documento legível por humanos e legível por máquinas. Um documento legível por humanos é escrito em uma linguagem natural e fácil de entender. Um documento legível por máquina deve aderir a uma especificação de API, como a especificação OpenAPI, que padroniza o formato para que seja consistente e possa ser integrado a sistemas futuros.

O projeto de APIs pode ser um processo altamente iterativo; especialmente se as APIs expuserem dados confidenciais, é importante testá-las rigorosamente em busca de bugs e falhas. Depois de construir algo, é importante ver se funciona como pretendido. Uma parte importante dos testes de APIs é o mocking, que é o processo de criar servidores fictícios com dados de amostra para verificar se a API se comunica com os endpoints corretamente e retorna os resultados esperados. 

O mocking pode ser realizado juntamente com os testes de API. Os testes de API incluem testes de contrato, que estabelecem como devem ser uma solicitação e uma resposta; testes unitários, que confirmam que um único endpoint entrega a resposta esperada; testes de carga, que testam se a API consegue funcionar sob pico de tráfego e testes de ponta a ponta, que validam as jornadas do usuário que envolvem comunicação com mais de uma API. Os testes podem ser feitos manualmente ou implementando frameworks de testes automatizados.

Se tudo estiver funcionando conforme o esperado, a API estará pronta para ser lançada e implementada. Neste momento, é importante que a documentação da API esteja finalizada para que outros usuários e suas máquinas possam integrar adequadamente essa API ao seu ambiente de rede de computadores. É possível que, depois que a API for lançada, os usuários encontrem problemas com ela que os stakeholders não anteciparam. É útil ter uma estratégia de controle de versão em vigor antes do lançamento da API para que, se os desenvolvedores precisarem atualizar a aplicação, isso seja feito de forma clara e consistente.

Uma abordagem API-first para o desenvolvimento de aplicação prioriza o projeto de APIs no início do processo de desenvolvimento de software e cria aplicação com serviços que serão entregues por meio de APIs. A ideia é que, ao priorizar o projeto de APIs no início do desenvolvimento de software, as APIs resultantes sejam mais reutilizáveis, seguras, eficientes, fáceis de usar e mais bem alinhadas com os objetivos da organização. Essa abordagem se opõe à abordagem code-first, que coloca a lógica do código em primeiro lugar, com os desenvolvedores criando APIs para se adequarem ao software posteriormente. 

O projeto de APIs é fundamental em uma abordagem API-first. Na API-first, as APIs são fundamentais para o desenvolvimento de aplicações e o projeto bem pensado promove o desenvolvimento de aplicações de melhor desempenho e mais valiosas. 

Práticas sólidas de projeto de APIs também podem ajudar a melhorar a experiência do desenvolvedor e a experiência do usuário final, descobrindo e resolvendo problemas de desenvolvimento e desempenho antes que eles se transformem em problemas maiores.

Os stakeholders podem estabelecer, desde o início do processo de desenvolvimento, que todos os aplicativos da empresa se integram e funcionam bem uns com os outros. Quando implementada com sucesso, uma abordagem API-first com documentação abrangente permite que os desenvolvedores reutilizem APIs existentes em vez de recriar funções que já existem.

As APIs REST (ou RESTful) têm estrutura flexível. O único requisito é que elas se alinhem aos seguintes seis princípios de projeto REST, também conhecidos como restrições arquitetônicas: interface uniforme, desacoplamento cliente/servidor, sem estado, cacheabilidade, arquitetura de sistema em camadas e, opcionalmente, código sob demanda. 

Essas restrições arquitetônicas tornam as APIs RESTful adequadas para uma abordagem API-first: o desacoplamento cliente/servidor e a falta de estado são particularmente úteis. 

Em uma API RESTful, as aplicações do cliente e do servidor devem ser independentes uma da outra. A única informação que a aplicação do cliente deve conhecer é o identificador uniforme de recurso (URI) do recurso solicitado; ele não pode interagir com a aplicação do servidor de nenhuma outra forma. 

As APIs RESTful também são sem estado, o que significa que cada solicitação precisa incluir todas as informações necessárias para seu processamento. Em outras palavras, as APIs REST não requerem quaisquer sessões do lado do servidor. Essas restrições tornam essas APIs independentes dos servidores de uma empresa, tornando-as flexíveis: aplicações do cliente e do servidor podem ser escritas com diferentes linguagens e protocolos sem afetar o projeto das APIs.

APIs RESTful também são uma boa opção para um ambiente API-first, pois são escaláveis e leves. A separação entre o cliente e o servidor melhora a escalabilidade porque as APIs RESTful não precisam reter informações de solicitações anteriores do cliente, reduzindo gargalos de comunicação. O cache eficaz também pode reduzir as interações cliente/servidor, outra vantagem para a escalabilidade. Como as APIs RESTful usam o formato HTTP para o transporte de mensagens, elas podem aceitar a transferência de dados em vários formatos. Isso pode simplificar a integração a novos ambientes.

Uma arquitetura de microsserviços é um estilo arquitetônico nativo da nuvem em que uma única aplicação é composta por muitos componentes menores vagamente acoplados e implementáveis de forma independente. As APIs REST são frequentemente usadas para permitir a comunicação entre esses serviços menores.

Uma abordagem API-first combina bem com o esquema de arquitetura de microsserviços porque as APIs são usadas para conectar os serviços juntos. Se o projeto de APIs for priorizado dentro de uma organização e as APIs forem projetadas para se comunicarem sem dificuldades entre si, os desenvolvedores economizarão tempo enquanto empacotam esses serviços em aplicações maiores. 

Para obter o máximo valor das APIs empresariais, as organizações geralmente enfatizam:

• Governança e documentação de APIs
• Coleta de feedback dos stakeholders
• Autenticação adequada
• Versão
• Padronização de mensagens de erro
• Escalonamento e contexto
• Consistência

Esses princípios ajudam a manter todos os stakeholders informados durante todo o processo de projeto de APIs e a garantir que as APIs estejam alinhadas às metas e à estratégia organizacionais.  

Governança e documentação de APIs: estabelecer uma estratégia de governança e documentação de APIs para toda a organização desde o início ajuda a promover a consistência e facilitar a navegação pelo portfólio de APIs de uma empresa. Por exemplo, uma organização pode optar por adotar uma especificação como o OpenAPI para que todas as APIs corporativas sigam um padrão de todo o setor. Em qualquer caso, manter a governança e a documentação adequadas e consistentes permite que novos usuários da API obtenham uma compreensão rápida da API e de suas funções. 

Coleta de feedback dos stakeholders: as entradas precoces dos principais stakeholders e consumidores de APIs ajudam a manter os desenvolvedores no caminho certo durante todo o processo de desenvolvimento. Uma comunicação deficiente pode levar a atrasos no desenvolvimento de APIs e APIs menos valiosas.

Autenticação adequada e segurança de APIs: para proteger APIs, bem como dados confidenciais, as organizações implementam técnicas de autenticação que fornecem validação para solicitações de API. Mecanismos de autenticação como chaves de API, OAuth e tokens da Web JSON (JWT) fornecem diferentes métodos de proteção de dados e tráfego de APIs. A criptografia de APIs, o processo de codificação de dados para deslocamentos entre o cliente e o servidor, também é usada para proteger dados e APIs.

Testes e controle de versão: os testes de APIs incluem a cobertura de vários cenários, positivos e negativos, para identificar problemas antes que uma API seja implementada. As APIs evoluem ao longo desses testes, e os desenvolvedores criam novas versões que corrigem bugs ou melhoram o desempenho. Novas versões de APIs também são lançadas por outros motivos, como quando os desenvolvedores adicionam novas funcionalidades a uma API. O controle de versão é como os desenvolvedores gerenciam alterações em uma API, tornam as alterações transparentes e garantem que as atualizações não interrompam os usuários atuais.

É útil ter mecanismos de controle de versão, como controle de versão baseado em URL ou baseado em cabeçalho, definidos antes do início do desenvolvimento. 

Padronização de mensagens de erro: o tratamento adequado de erros melhora a experiência do consumidor de APIs, pois ajuda na solução de problemas quando algo dá errado. Os códigos, mensagens e respostas de erros precisam descrever com precisão a natureza do erro e permanecer claros e consistentes.

Contexto e restrições: cada API existe em um contexto específico que determina como ela será criada e quais são as suas funções. Prazos de projeto concorrentes, volumes de tráfego esperados e se a empresa é API-first ou code-first podem moldar a API resultante. É importante que todos os stakeholders estejam cientes dessas informações para que possam tomar decisões informadas durante o processo de desenvolvimento.

Consistência: acima de tudo, manter tudo consistente geralmente leva a um melhor projeto de APIs. A consistência no projeto de APIs vai além do controle de versão e dos códigos de erros. Ao definir endpoints, manter as convenções de nomenclatura consistentes pode facilitar a identificação. Ao fazer uma solicitação específica a uma API, ela deve ser resolvida sempre da mesma maneira. Quando tudo é consistente em um cenário de API, também é mais fácil documentar as APIs para que elas sejam compreensíveis para futuros usuários.