Os 5 estilos de API mais populares e o que os distingue

No que diz respeito aos casos de utilização, vale a pena mencionar que as APIs podem ser públicas, disponíveis para parceiros ou totalmente internas. Este primeiro fator diferenciador define o padrão para muitas das características e funcionalidades que necessitarão de desenvolvimento: como os dados são armazenados e partilhados, como as credenciais são geridas, quanto tráfego a API precisa de suportar, etc.

Como verá, os seguintes estilos arquitetónicos podem ser utilizados em qualquer um destes três casos, mas algumas combinações fazem mais sentido do que outras.

Estas são, de longe, as APIs mais comuns atualmente e também o estilo que utilizámos para construir a WebScrapingAPI. A sigla significa REpresentational State Transfer, e o estilo determina que, se você, como cliente, fizer uma solicitação, a API enviará de volta uma representação do estado do recurso que solicitou.

As APIs RESTful baseiam-se fortemente na infraestrutura HTTP. Uma vez que a Web em geral utiliza principalmente HTTP, as APIs REST já têm uma vantagem, pois são fáceis de compreender, integrar e utilizar.

Este estilo é também definido por um conjunto de restrições que a API deve respeitar. Embora isto possa parecer um incómodo à primeira vista, as restrições garantem que a API se comporta de forma previsível e útil. Existem seis no total, e são as seguintes:

• Interface uniforme
• Sem estado
• Cacheável
• Cliente-servidor
• Sistema em camadas
• Código sob demanda

Publicámos um artigo completo sobre estas restrições no Medium, por isso consulte-o para conhecer os detalhes mais específicos relativos às APIs REST.

Se uma API respeitar algumas destas restrições, mas não todas, pode ser considerada semelhante a REST. Em alguns casos de utilização, as restrições podem trazer mais problemas do que benefícios, razão pela qual poderá deparar-se com adoções parciais deste estilo.

O SOAP, ou Simple Object Access Protocol, depende fortemente do XML. Para o utilizar, tem de seguir normas rigorosas relativas à estrutura das mensagens, regras de codificação e tratamento de pedidos e respostas.

Embora sejam muito precisas e abrangentes, as APIs SOAP podem ser mais difíceis de se habituar devido à sua linguagem de marcação. As solicitações e respostas podem ficar bastante longas e complexas, tornando-as uma tarefa árdua se digitar manualmente os comandos.

Pelo lado positivo, este estilo tem a vantagem de incluir o tratamento de erros. Se se deparar com um problema na solicitação, a resposta conterá muitas informações valiosas que podem ajudá-lo a encontrar e corrigir o erro.

Este estilo é utilizado para consultar bases de dados a partir de aplicações do lado do cliente através de HTTP. Mas, em vez de enviar várias solicitações HTTP para diferentes pontos finais, pode enviar uma única «consulta» POST para tudo o que precisa. Essencialmente, o cliente descreve o que precisa uma vez, e a API faz o seu melhor para recuperar esses dados.

Um servidor a operar sob a arquitetura GraphLQ possui um modelo (ou esquema) pré-definido para os dados que podem ser solicitados. Assim, quando faz uma solicitação, o esquema funciona como uma diretriz sobre o que pode solicitar, como a informação deve ser estruturada e como pode interagir com o servidor.

A vantagem deste sistema é que os utilizadores têm uma compreensão clara do que podem obter, pelo que é altamente improvável recuperar dados falsos ou deparar-se com um erro. O princípio subjacente é colocar o cliente em primeiro plano e proporcionar-lhe a melhor experiência.

À semelhança do GraphLQ, as APIs Falcor criam um ficheiro JSON virtual que funciona como um contentor para os dados que um cliente receberá após uma solicitação. Este ficheiro virtual pode ser ampliado com cada novo dado de que o cliente necessite. Embora isto acrescente comodidade, o ficheiro pode tornar-se bastante grande com o tempo.

Felizmente, não é necessário recuperar o ficheiro JSON completo a cada pedido. Em vez disso, pode especificar quais as partes de que necessita em qualquer momento e obtê-las na resposta. Isto funciona porque o ficheiro JSON é publicado numa URL e contém ligações para diferentes recursos no backend. Essencialmente, pode navegar pelo ficheiro virtual à procura dos dados que deseja.

Esta camada virtual entre o cliente e o servidor ajuda a ligar os dois, mantendo as suas arquiteturas completamente independentes.

Quando tem poucas restrições com que se preocupar, o gRPC deve ser uma das suas primeiras opções ao projetar uma API. É independente de linguagem e de plataforma, e bastante rápido devido ao uso de Protocol Buffers (protobufs) para serializar dados em fluxos binários. Esses dados são então transferidos através de HTTP/2.

O gRPC é adequado para sistemas distribuídos. O aspeto mais importante deste estilo são os procedimentos. Pode executá-los na máquina local e em dispositivos remotos. Em ambos os casos, chamar um procedimento é rápido e simples.

Uma das razões pelas quais as APIs estão a tornar-se populares são as vantagens que os microsserviços apresentam em relação ao modelo clássico de software de serviço único. Desta forma, cada funcionalidade/microsserviço pode ser concebido, desenvolvido e atualizado separadamente, sem comprometer outros componentes. Nesse sentido, o gRPC é uma excelente solução para unir tudo isto.

Além disso, como é possível iniciar um procedimento remotamente, é também uma boa opção para ligar dispositivos móveis a serviços de backend.

Embora este artigo tenha-lhe oferecido uma visão geral dos estilos arquitetónicos de API mais comuns, isso não é suficiente para garantir que escolha o mais adequado. Para nós, enquanto equipa, foi essencial ter experiência prática em primeira mão com o maior número possível de exemplos.

Por experiência, refiro-me tanto à de utilizador como à de programador. Afinal, talvez haja um estilo com o qual esteja mais familiarizado, pelo que seria mais fácil de construir, mas tem de se colocar no lugar do utilizador final e ver como isso funciona para ele.

Um estilo não é algo que se possa simplesmente escolher a meio do desenvolvimento ou mudar mais tarde. É um conjunto de regras que dita a forma como a API se concretiza. Como tal, é uma decisão importante.

Um primeiro passo que pode dar é ler a documentação das APIs já existentes no mercado e, idealmente, testá-las. Experiência anterior na criação de APIs também seria uma grande vantagem.

Se quiser ver como transformámos a WebScrapingAPI na potência de web scraping que é hoje, por que não consultar a nossa documentação? Nem todas as suas funcionalidades atuais estavam presentes no lançamento. Opções como o scraping de endpoints de API REST ou de ficheiros foram adicionadas a pedido dos nossos utilizadores, por isso lembre-se: o estilo arquitetónico destina-se a dar-lhe uma orientação, mas cabe-lhe a si moldar a API para que se torne algo que as pessoas vão adorar.