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

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

Como poderá 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 padrão que utilizámos para criar a WebScrapingAPI. A sigla significa REpresentational State Transfer (Transferência de Estado Representacional), e o padrão determina que, se você, enquanto cliente, efetuar uma solicitação, a API devolverá uma representação do estado do recurso que solicitou.

As APIs RESTful assentam em grande parte na infraestrutura HTTP. Uma vez que a Web, em geral, utiliza principalmente o HTTP, as APIs REST já apresentam 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 comporte de forma previsível e útil. São seis no total, e são as seguintes:

• Interface uniforme
• Apátrida
• Pode ser armazenado em cache
• Cliente-servidor
• Sistema em camadas
• Código sob demanda

Publicámos um artigo completo sobre estas restrições no Medium, por isso não deixe de o consultar para conhecer os pormenores 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 é possível encontrar adoções parciais deste estilo.

O SOAP, ou Protocolo Simples de Acesso a Objetos, baseia-se fortemente no XML. Para o utilizar, é necessário respeitar normas rigorosas no que diz respeito à estrutura das mensagens, às regras de codificação e ao tratamento de pedidos e respostas.

Embora sejam muito precisas e abrangentes, as APIs SOAP podem ser mais difíceis de dominar devido à sua linguagem de marcação. Os pedidos e as respostas podem tornar-se bastante longos e complexos, o que torna a tarefa tediosa se os comandos forem digitados manualmente.

Por outro lado, este estilo tem a vantagem de incluir um mecanismo de tratamento de erros integrado. Se surgir algum problema com o pedido, a resposta conterá muita informação útil que pode ajudar a identificar 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. No entanto, em vez de enviar várias solicitações HTTP para diferentes pontos de extremidade, pode enviar uma única solicitação POST com toda a informação necessária. Essencialmente, o cliente descreve o que precisa uma única vez, e a API faz o possível para recuperar esses dados.

Um servidor que opera sob a arquitetura GraphLQ possui um modelo (ou esquema) pré-definido para os dados que podem ser solicitados. Assim, quando se faz uma solicitação, o esquema funciona como um guia sobre o que se pode solicitar, como a informação deve ser estruturada e como se 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 que obtenham dados incorretos ou se deparem com um erro. O princípio subjacente consiste em colocar o cliente em primeiro plano e proporcionar-lhe a melhor experiência possível.

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

Felizmente, não é necessário recuperar o ficheiro JSON na íntegra em cada pedido. Em vez disso, pode especificar quais as partes de que necessita em cada momento e obtê-las na resposta. Isto funciona porque o ficheiro JSON está 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 há poucas restrições com que se preocupar, o gRPC deve ser uma das suas primeiras opções ao conceber uma API. É independente da linguagem e da plataforma e bastante rápido, graças à utilização de Protocol Buffers (protobufs) para serializar dados em fluxos binários. Esses dados são depois transferidos através de HTTP/2.

O gRPC é ideal para sistemas distribuídos. O aspeto mais importante deste estilo são os procedimentos. É possível executá-los tanto na máquina local como em dispositivos remotos. Em ambos os casos, a chamada de um procedimento é rápida e simples.

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

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

Embora este artigo lhe tenha proporcionado 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 à minha experiência como utilizador como à minha experiência como programador. Afinal, talvez haja um estilo com o qual estejas mais familiarizado, pelo que seria mais fácil de implementar, mas tens de te 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 alterar mais tarde. É um conjunto de regras que determina a forma como a API se configura. Como tal, é uma decisão importante.

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

Se quiseres saber como transformámos a WebScrapingAPI na potência de web scraping que é hoje, porque não consultas a nossa documentação? Nem todas as funcionalidades atuais estavam presentes no lançamento. Opções como a extração de dados de pontos de extremidade de API REST ou de ficheiros foram adicionadas a pedido dos nossos utilizadores, por isso lembra-te: o estilo arquitetónico destina-se a dar-te uma orientação, mas cabe-te a ti moldar a API para que se torne algo que as pessoas vão adorar.