As interfaces de programação de aplicações (API) definem as normas e os protocolos que permitem que diferentes componentes de software se comuniquem entre si. Permitem que as aplicações solicitem dados e ações a sistemas independentes.
As APIs estão em todo o lado. Estão na base de praticamente todas as interações com os seus dispositivos e software. Por exemplo, as aplicações no seu telefone utilizam APIs para obter dados dos seus servidores e, em seguida, dependem de APIs separadas fornecidas pelo iOS e pelo Android para colocar os dados no ecrã, enviá-los para você através de notificações push ou partilhá-los com um contato.
Como existem muitas formas de APIs, pode ser confuso entender como se encaixam. Que tipos de APIs existem? Quando é que algo pode ser considerado uma API? Como é que pode criar a sua própria? Neste guia completo, encontrará as respostas a todas estas perguntas.
O que são as APIs?
O termo interface de programação de aplicações pode parecer obtuso, mas refere-se a um conceito específico. Na sua forma mais simples, uma API é algo que permite aos programadores programar código que funciona com uma aplicação. Define uma interface que facilita a interoperabilidade ou as regras, procedimentos, expectativas e normas que dois ou mais sistemas devem respeitar.
Vamos explorar esta ideia com um exemplo: considere uma plataforma de identidade que expõe uma API para registar novos usuários. As aplicações externas podem utilizar a API para criar usuários a pedido, mas para que isso funcione, os dados têm de estar num formato que a plataforma espera.
A API define estes requisitos: pode indicar que a aplicação do cliente deve fazer um pedido HTTP POST para example.com/users; que os campos de dados Nome, Email e Palavra-passe têm de ser incluídos; e que um corpo JSON será emitido em resposta, contendo o ID do novo usuário. Com estas informações, os programadores podem utilizar a API para registar com êxito novos usuários.
Essencialmente, uma API é uma combinação do código da plataforma que os programadores podem chamar e a documentação que explica como a utilizar.
Porque é que as APIs são importantes?
As APIs permitem o fluxo de dados entre sistemas. Isto permite que o software se baseie noutras aplicações, criando soluções mais poderosas.
As APIs são também essenciais para a automatização. Ao combinar as capacidades de diferentes APIs numa única aplicação, pode mover dados entre sistemas à medida que ocorrem ações e eventos. Os programadores podem escrever algumas linhas de código para implementar processos complexos que, de outra forma, exigiriam uma programação manual meticulosa.
Por exemplo, a raspagem da web é uma tarefa complexa. Para implementar um raspador da web eficaz, os programadores teriam de criar uma lógica sofisticada para controlar uma instância do navegador web, configurar proxies de geolocalização e contornar CAPTCHAs. Ao selecionar uma API, pode aceder a todas estas funcionalidades com alguns pedidos de rede. Depois, pode utilizar outras APIs para manipular os dados raspados, analisá-los e enviar os resultados para um membro da equipa na sua plataforma de chat.
Além disso, as APIs são um ativo comercial. Facilitar a integração com outras ferramentas torna as suas plataformas mais atraentes para os clientes. Os programadores externos são livres de criar as suas próprias soluções, que são maiores do que a soma das suas partes.
As APIs são de importância vital para os processos hiperconectados de hoje. Muitas tecnologias que são tidas como garantidas são alimentadas por uma intrincada rede de APIs. Por exemplo, as compras em linha envolvem normalmente APIs de coleta de pagamentos, de pedidos de envio e de entrega de correio eletrónico alojadas por vários fornecedores independentes.
Tipos de APIs
As APIs individuais oferecem diferentes funções para corresponder ao serviço de que fazem parte. Por exemplo, uma solução de gestão de identidades oferecerá capacidades de API muito diferentes das de um fornecedor de raspagem de motores de busca.
No entanto, as características técnicas de APIs aparentemente não relacionadas são frequentemente muito semelhantes. As APIs mais populares utilizam um conjunto de normas diferentes, que representam técnicas que a indústria do software considerou eficazes para integrar sistemas.
Vejamos os diferentes tipos de APIs:
#REST
A Transferência de Estado Representacional (REST) foi teorizada pela primeira vez por Roy Fielding em 2000 e é atualmente utilizada pela maioria dos serviços web.
A REST representa os dados de um sistema como recursos sem estado que são mapeados para URLs HTTP. Os métodos HTTP (GET, POST, PUT e DELETE) são utilizados para obter recursos e realizar ações sobre eles.
Por exemplo, um pedido GET a example.com/users/100 deve devolver as seguintes informações sobre o usuário com ID 100:
{
"Id": 100,
"Name": "Example User",
"Email": "[email protected]"
}Se depois emite um pedido DELETE para o mesmo URL, o serviço deve destruir o objeto.
A REST é popular porque é fácil de implementar, baseia-se no HTTP e modela eficazmente a forma como muitas aplicações do mundo real tratam os seus dados. As interações com muitos sistemas são frequentemente uma combinação de um verbo (DELETE, apagar) e um substantivo (user, usuário), e esta arquitetura pode ser diretamente expressa por REST.
#SOAP
Ao contrário da REST, o Protocolo Simples de Acesso a Objetos (SOAP) é uma especificação formal para a partilha de dados. Todos os intercâmbios do SOAP utilizam o formato de dados XML, enquanto as APIs de REST podem oferecer JSON, XML, CSV ou uma alternativa específica da plataforma. Uma simples chamada à API do SOAP poderia produzir uma resposta como esta:
xml
<?xml version="1.0" ?>
<soap:Envelope
xmlns:soap="https://www.w3.org/2003/05/soap-envelope/"
soap:encodingStyle="https://www.w3.org/2003/05/soap-encoding">
<soap:Body>
<m:GetUserResponse>
<m:Id>100</m:Id>
<m:Name>Example User</m:Name>
<m:Email>[email protected]</m:Email>
</m:GetUserResponse>
</soap:Body>
</soap:Envelope>
A utilização de XML e a inclusão de atributos específicos do protocolo tornam o SOAP mais detalhado do que as APIs de REST típicas. No entanto, as vantagens de normalização do SOAP significam que é preferido por muitas grandes empresas e sistemas comerciais. As operações disponíveis na API são explicitamente definidas por esquemas XML. Estas descrevem a estrutura e os tipos de dados de cada pedido e resposta, reduzindo o risco de ocorrência de incompatibilidades entre cliente e servidor.
#GraphQL
GraphQL é uma tecnologia relativamente nova para a construção de APIs manipuláveis. Foi desenvolvida no Facebook em 2012 e publicada abertamente em 2015.
GraphQL foi concebida para resolver vários dos desafios das APIs de REST e SOAP. Simplifica as consultas complexas, fornecendo uma linguagem expressiva que o cliente pode utilizar para extrair dados da API. GraphQL permite-lhe obter apenas os campos de dados específicos de que necessita, em vez de fornecer sempre objetos inteiros. Isto evita o desperdício de transferências de dados redundantes.
Aqui está uma consulta de GraphQL simples para obter o correio eletrónico de um usuário:
{
user {
Email
}
}Esta consulta produziria a seguinte resposta:
json
{
"user": {
"Email": "[email protected]"
}
}GraphQL está a ganhar popularidade porque é uma opção mais versátil que se adequa melhor às atuais aplicações altamente conectadas, em que pequenas porções de dados são obtidas de forma independente por vários componentes diferentes. No entanto, a implementação de GraphQL pode ser relativamente complexa e é mais bem tratada com ferramentas específicas de linguagem de programação.
#RPC
As Chamadas de Procedimento Remoto (RPC) são uma forma simples de API. A técnica refere-se à chamada de uma função remota como se estivesse disponível localmente. Um pedido de rede básico faz com que o servidor da API execute a tarefa e forneça o resultado. O cliente não está exposto aos pormenores da comunicação de rede.
As APIs de RPC são semelhantes às interfaces de programação funcional. Tanto o verbo como o substantivo serão incluídos no URL que chamar, tal como example.com/deleteUser?User=100. Isto contrasta com a REST, onde se aplica um verbo a um substantivo específico (DELETE example.com/users/100). A RPC mapeia mais diretamente o código, enquanto a REST tenta modelar a sua estrutura de dados.
A RPC é fácil de utilizar tanto pelo cliente como pelo servidor. Trata-se de uma coleção de URLs que aceitam vários parâmetros de pedido e enviam dados em resposta. No entanto, não existe uma normalização e estas APIs tendem a ser difíceis de explorar pelos programadores. Enquanto os pontos finais da maioria das APIs de REST podem ser antecipados quando se sabe os nomes dos recursos do serviço, e os URLs utilizados para RPC serão únicos para cada plataforma.
Os projetos modernos, como gRPC, estão a introduzir melhorias na RPC. Trata-se de uma estrutura que funciona com várias linguagens de programação e pode ser utilizada para definir rapidamente serviços de API de RPC que comunicam com clientes utilizando Protocol Buffers, a abordagem de desempenho da Google, para serializar dados estruturados.
APIs do sistema
As APIs de REST, SOAP, GraphQL e RPC são utilizadas no contexto das comunicações de rede entre sistemas. Existem outras APIs para diferentes tipos de integração, como as interfaces de sistema que permitem às aplicações aceder às funções do seu dispositivo.
Estas APIs são fornecidas por sistemas operativos como Windows, Android e iOS. São expostas por estruturas de programação e SDKs que os programadores podem chamar a partir do seu código. As APIs do sistema permitem um acesso conveniente a funcionalidades como notificações, ícones de lançador, reprodução de multimédia e acesso a sensores do dispositivo sem que os programadores tenham de escrever código de baixo nível.
APIs de linguagens de programação
Do mesmo modo, as linguagens de programação e as dependências têm as suas próprias APIs. Os módulos incluídos na biblioteca padrão de uma linguagem representam uma API. Os pacotes de terceiros que instala no seu projeto são também APIs, e os componentes que escreve estão ligados entre si através de interfaces definidas.
A API é a distinção entre o funcionamento interno de um sistema, que pode mudar a qualquer momento, e a interface externa estável em que os integradores confiam. Os métodos e funções marcados como públicos na sua base de código criam uma API que outro código pode consumir.
APIs síncronas e assíncronas
As APIs podem ser síncronas ou assíncronas. Uma API síncrona devolverá imediatamente o resultado da operação solicitada, enquanto uma API assíncrona pode continuar a execução após a conclusão do intercâmbio de dados.
Para uma API de coleta de dados, pedir os dados atualmente coletados seria uma tarefa síncrona que devolveria sempre os dados recuperados até à data. O pedido de uma nova raspagem de dados pode ser assíncrono porque é provável que o processo demore muito tempo a ser concluído. É mais eficiente para a API terminar a comunicação imediatamente após informar o cliente de que a coleta foi agendada.
Um olhar detalhado: Como funcionam as APIs
Cada um dos tipos de API comuns tem a sua própria gramática. Por exemplo, a REST funciona com objetos e verbos, enquanto GraphQL oferece uma solução mais versátil que é centrada no cliente em vez de centrada no servidor. Vamos analisar mais pormenorizadamente estas duas opções:
# REST
A REST utiliza verbos de método HTTP para realizar ações em recursos. Os métodos mais comuns são GET, POST, PUT e DELETE:
– GET /users/100 devolve o ID com o usuário 100.
– POST /users cria um novo usuário.
– PUT /users/100 atualiza um usuário por ID.
– DELETE /users/100 elimina um usuário por ID.
Isto ilustra a sintaxe de REST básica. O URL fornece o ID do objeto com que você está a interagir e o substantivo plural de que é uma instância. O método HTTP utilizado pelo cliente determina a ação que será executada.
Quando uma ação requer dados adicionais para ser concluída, estes são fornecidos como carga útil do pedido HTTP. Por exemplo, ao criar um usuário com POST /users, o corpo conterá o nome de usuário e a palavra-passe a atribuir.
A API responde a cada pedido com um código de estado HTTP que descreve o seu resultado. Por exemplo, uma resposta 404 Not Found para GET /users/100 indica que o ID de usuário 100 não existe, enquanto 202 Accepted para DELETE /users/100 significa que o usuário foi eliminado com êxito.
#GraphQL
Em comparação, GraphQL é uma abordagem diferente para APIs. É comercializada como [“uma linguagem de consulta para a sua API,”](https://graphql.org) dando a entender a funcionalidade mais avançada que suporta. Enquanto a REST desperdiça frequentemente largura de banda ao incluir propriedades de objetos indesejadas, GraphQL permite-lhe pedir os dados exatos que pretende.
As APIs que usam GraphQL são criadas como serviços, que definem os pontos finais que os clientes podem chamar. Um serviço é um esquema tipificado para uma entidade. A cada campo do esquema é atribuído um tipo de dados específico:
type Team {
id: ID
name: String
}
type User {
id: ID
name: String
email: String
team: Team
}
É possível obter dados de esquemas utilizando consultas:
{
user(id: 100) {
email,
team {
name
}
}
}
Esta consulta de exemplo poderia retornar os seguintes dados:
{
"email": "[email protected]",
"team": "Example Team"
}
Os campos da consulta são suportados por resolvedores. Quando a consulta é executada, os resolvedores são responsáveis por produzir um valor para cada campo. No exemplo anterior, o resolvedor de team extrairia a propriedade name da equipa atribuída ao usuário solicitado em vez de devolver o objeto inteiro.
GraphQL também fornece uma maneira consistente de atualizar dados usando mutações. As mutações são semelhantes às consultas, mas causam uma alteração de estado no servidor. As mutações são implementadas através da definição de uma função para cada campo nos seus serviços. Esta função é responsável por guardar um novo valor no campo.
As APIs de GraphQL são normalmente criadas adicionando uma biblioteca de cliente GraphQL ao seu projeto. Estas ferramentas permitem-lhe gerar convenientemente esquemas de GraphQL a partir dos seus modelos ORM existentes e de outro código.
Como integrar APIs
A integração de uma API descreve o processo de adoção de uma API num sistema de software. Embora a API ofereça funções prontas a utilizar, ainda tem de escrever algum código personalizado para as utilizar no seu projeto.
Uma integração típica de API envolve as seguintes etapas:
1. Avaliar as opções disponíveis: Para começar, é necessário avaliar as diferentes APIs que resolvem o seu caso de utilização, e identificar a melhor para o seu produto. Isto inclui verificar a qualidade da documentação, se existe uma comunidade ativa a utilizar a API e a rapidez com que os responsáveis pela manutenção respondem aos pedidos de apoio, aos problemas de segurança e aos relatórios de correção de erros.
2. Inscrever-se no serviço e solicitar uma chave de API: Algumas APIs são expostas publicamente e não requerem autenticação, mas a maioria das APIs exigirá que se registe e obtenha uma chave de API quando exceder alguns limites básicos de utilização. As chaves de API devem ser tratadas como valores sensíveis e armazenadas de forma segura: não as codifique no código do seu projeto. A chave autentica-o no serviço e identifica a sua aplicação para efeitos de limitação de taxa e controlo da utilização.
3. Procurar uma biblioteca de cliente de API para a sua linguagem de programação: Pode integrar APIs fazendo pedidos diretos de rede utilizando a biblioteca HTTP da sua linguagem de programação. No entanto, muitos fornecedores de APIs também oferecem bibliotecas de clientes e SDKs que envolvem a API para fornecer uma linguagem de programação mais conveniente. Optar por utilizar uma biblioteca de clientes quando esta estiver disponível simplificará ainda mais a sua implementação e o protegerá de quaisquer alterações significativas à API subjacente.
4. Escrever o seu código: Depois de identificar a sua biblioteca, é altura de escrever o código que interage com a API. Terá de configurar a biblioteca que está a utilizar com a chave da API que obteve. O seu código pode também ter de definir quaisquer parâmetros de configuração que o serviço exija, como a região do centro de dados e o formato de resposta preferido.
5. Testar a integração da API: Por fim, teste a sua integração para se certificar de que funciona como esperado. Os seus testes devem incluir verificações das rotinas de tratamento de erros, como o que acontece se a API não estiver disponível. Isto ajudará a garantir que a sua aplicação seja resiliente quando o serviço esteja fora de linha.
Também é importante considerar as implicações de segurança da integração de uma API. Embora as APIs de terceiros possam simplificar as principais tarefas de desenvolvimento, deve agir com cautela ao enviar dados do usuário para um serviço externo. A plataforma será capaz de cumprir as mesmas normas de segurança que a sua? Se você puder replicar facilmente a funcionalidade de uma API, pode ser mais seguro criar a sua própria implementação na sua aplicação.
Exemplo de API na vida real
Pronto para utilizar uma API? Para experimentar rapidamente APIs da web, pode utilizar ferramentas HTTP que já tem no seu computador, incluindo curl e wget. Se preferir interfaces gráficas, Postman é uma boa alternativa.
Obter dados falsos com Faker
O projeto Faker API é uma coleção popular de APIs que devolvem dados gerados aleatoriamente sobre uma variedade de assuntos. Faker API é frequentemente utilizada durante o desenvolvimento de produtos para preencher interfaces antes de o verdadeiro backend estar disponível.
Faker API utiliza os princípios da REST, com o substantivo no final do URL definindo o tipo de dados a gerar:
$ curl https://fakerapi.it/api/v1/books?_quantity=1
{
"status": "OK",
"code": 200,
"total": 1,
"data": [
{
"id": 1,
"title": "Duck and a pair of.",
"author": "Jessyca McKenzie",
"genre": "Sit",
"description": "ALL RETURNED FROM HIM TO YOU,\"' said Alice. 'I wonder how many miles I've fallen by this time, as it can be,' said the Cat. '--so long as I used--and I don't take this child away with me,' thought.",
"isbn": "9796054956226",
"image": "http://placeimg.com/480/640/any",
"published": "2010-09-14",
"publisher": "Quod Enim"
}
]
}
Raspagem de listagens de motores de busca com Bright Data
A Bright Data fornece um conjunto abrangente de APIs de SERP e APIs de proxy, e é uma plataforma comercial na qual é necessário registar-se:
Para começar a utilizá-la, registe-se para um teste gratuito e siga a documentação para adicionar a API de SERP à sua conta. Em seguida, é necessário ativar o modo assíncrono nas Opções avançadas da API:
Depois de ativar a API, pode enviar um pedido POST para reunir os resultados do motor de busca:
$ curl -i "https://brightdata.com/api/serp/req?customer={CUSTOMER_ID}&zone={CUSTOMER_ZONE}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {API_TOKEN}" \
-d '{"country":"us","query":{"q":"apis"}}'
...
x-response-id: s3wt2t...Gere um token de API nas definições da sua conta e, em seguida, substitua-o no comando em vez de `{API_TOKEN}`:
Pode encontrar os respetivos valores dos outros marcadores para a sua conta, {CUSTOMER_ID} e {CUSTOMER_ZONE}, no parque de diversões da API de SERP.
Esta consulta de exemplo utiliza a API para agendar uma pesquisa de apis no Google dos EUA. Copie o valor do cabeçalho de resposta x-response-id apresentado na resposta do comando. Pode utilizar este valor para obter o resultado de SERP depois de este ter sido gerado. Aguarde um minuto e, em seguida, faça o seguinte pedido:
$ curl "https://brightdata.com/api/serp/get_result?customer={CUSTOMER_ID}&zone={CUSTOMER_ZONE}&output=json&response_id={RESPONSE_ID}"Substitua RESPONSE_ID pelo valor que copiou anteriormente. Os dados gerados pela sua pesquisa serão apresentados na sua consola.
Estes pontos finais são um exemplo de uma API de RPC. Se a API for RESTful, os URLs terão o seguinte aspeto:
POST /api/serp/request e GET /api/serp/results/{RESPONSE_ID}.
Resumo
As APIs são interfaces claramente definidas que podem ser utilizadas para ligar, de forma fiável, diferentes componentes de software. No entanto, o que constitui uma API pode ser confuso porque existem muitas formas, variantes e casos de utilização diferentes.
Em geral, uma API é um mecanismo que o código pode e deve utilizar para aceder a funções implementadas por outro código. A API é suportada pelo programador do sistema remoto e documentada com instruções sobre como a utilizar. Isto cria um contrato entre o serviço e as aplicações do cliente que utilizam a API. Se o cliente enviar dados no formato esperado, é garantido que obterá uma resposta com uma estrutura previsível.
As APIs simplificam a implementação de funcionalidades especializadas nos seus sistemas. Pode deixar que os especialistas do sector façam o trabalho árduo por você e depois ligar as suas plataformas ao seu código. Tente usar o conjunto de APIs de SERP e APIs de proxy da Bright Data para realizar suas tarefas de raspagem da web.
