APIs para leigos: Tudo o que precisa de saber

Uma API (Interface de Programação de Aplicações) é um conjunto de funções que permite que as aplicações acedam a dados e interajam com componentes de software externos, sistemas operativos ou microsserviços. Para simplificar, uma API entrega um pedido do utilizador a um sistema e envia a resposta do sistema de volta ao utilizador.

As APIs são muito utilizadas porque podem facilitar muito as coisas e acelerar o processo de desenvolvimento de outros sistemas e aplicações. Por exemplo, se estiver a criar o seu próprio software e desejar integrar reconhecimento facial ou processamento de pagamentos, o melhor é utilizar uma API. Basta ligar o seu software a outro. Estas são fornecidas com a documentação da API, um manual para programadores que ajuda a implementar as funcionalidades desejadas.

Ao utilizar uma API, não precisa de lidar com qualquer código-fonte nem sequer de compreender como funciona. Parece bom, certo? Ótimo, vamos ver como é que as APIs fazem isso.

Pense numa API como o «intermediário» entre a sua aplicação e o servidor. Diz à sua aplicação para fazer algo por si; depois, a aplicação utilizará uma API para comunicar com o servidor web, dizendo-lhe o que fazer. Esta ação é chamada de pedido. Posteriormente, o servidor enviará uma resposta para ser entregue pelo «intermediário» à sua aplicação.

Vamos ver um exemplo menos abstrato. Entras num restaurante, escolhes uma mesa com vista e esperas que o empregado anote o teu pedido. Neste caso, o empregado é o teu “intermediário”, porque o cozinheiro não pode anotar o teu pedido diretamente, já que tem outros pedidos para preparar na cozinha. Fazes um pedido ao empregado, o empregado envia esse pedido para a cozinha, recebe uma resposta — neste caso, o teu pedido — e leva-o até à tua mesa. Bom apetite!

Até a API é uma abstração do servidor web, já que a aplicação não sabe o que se passa na «cozinha», apenas qual será o resultado final. O utilizador final sabe que, se pedir um bolo do menu, receberá um bolo. Existem muitos tipos de APIs, dependendo da finalidade para a qual foram criadas ou da sua política de lançamento. Vamos dar uma olhadela a estes diferenciadores.

As APIs são úteis. Como mencionámos acima, a comunicação entre vários softwares e aplicações é essencial para atingir um objetivo específico, por isso uma API é concebida com base no que se pretende alcançar. Vejamos alguns exemplos:

• As APIs de bases de dados facilitam a comunicação entre uma aplicação e um sistema de gestão de bases de dados. Por exemplo, o Firebase é uma plataforma de aplicações web móveis da Google que permite aos programadores sincronizar e armazenar dados em tempo real de forma simples, sem terem de gerir servidores ou escrever código do lado do servidor.
• APIs de sistemas operativos. Até os sistemas operativos têm um número considerável de APIs, por exemplo, a API do Windows ou a API do Espaço de Utilizador do Kernel do Linux. Também é possível encontrar as APIs fornecidas pela Apple para o macOS e o iOS, apresentadas na documentação para programadores.
• As APIs remotas interagem através de uma rede de comunicações. A rede de comunicações mais comum é a Internet, pelo que as APIs são normalmente concebidas com base em padrões web. Mas isso não significa que todas as APIs remotas sejam APIs web. Ainda assim, as APIs web são geralmente remotas, utilizam tipicamente HTTP para mensagens de pedido e definem a estrutura das mensagens de resposta. É preferível que estas mensagens estejam no formato XML ou JSON, uma vez que é mais fácil para outras aplicações analisarem a informação.
• As APIs mais utilizadas são as APIs Web, porque enviam pedidos a partir de uma aplicação Web e respostas a partir de servidores utilizando HTTP (Hypertext Transfer Protocol). Os programadores utilizam essas APIs Web nas suas aplicações ou sites, aumentando a sua funcionalidade e tornando-as mais práticas para o utilizador, como integrar um método de início de sessão através do Facebook ou do Google ou adicionar um mapa utilizando a API do Google Maps.

Algumas APIs são criadas apenas para uso interno. Isto é particularmente comum em grandes empresas. Outras são concebidas como produtos destinados a integrar-se com qualquer software que os clientes utilizem. Estas são as principais categorias:

As APIs privadas são utilizadas principalmente dentro da própria organização, integrando-as em sistemas e aplicações utilizados pelos seus colaboradores e melhorando o funcionamento interno. Mesmo que pareçam abertas ao público, a interface permanece disponível apenas para quem está dentro da organização, que tem controlo total sobre a API. Isto também reduz alguns custos para a organização.

As APIs de parceiros podem proporcionar fontes de receita adicionais, uma vez que são partilhadas com um ou mais parceiros comerciais. É celebrado um acordo entre o referido parceiro e o editor. Uma API de parceiro também acrescenta valor ao serviço e abre um canal para vendas adicionais.

As APIs públicas estão disponíveis para quaisquer programadores terceiros. Este tipo de APIs não requer uma relação próxima entre o utilizador e o editor; podem aumentar a fonte de receitas, ajudar a alcançar públicos mais vastos e gerar tráfego, além de apoiar muitas causas e uma variedade de iniciativas empresariais. As APIs públicas podem ser:

• Abertas: Estas APIs podem ser utilizadas por qualquer pessoa da forma que desejar, o que significa que não existem termos ou condições restritivos, não é necessário o consentimento do editor para utilizar a API e não é necessário pagar por ela. Fornecem documentação pública para acesso dos programadores e podem ser utilizadas para testar e criar aplicações.
• Comerciais: Para utilizar essas APIs, terá de pagar uma taxa de subscrição. Para que os utilizadores possam testar e avaliar o produto, os editores oferecem frequentemente um período de teste gratuito, para que o cliente saiba se deve ou não adquirir uma subscrição.

De particular interesse são as APIs SOAP e as APIs REST, uma vez que estas são muito difundidas. Vamos dar uma vista de olhos aos conceitos por trás das siglas:

As APIs SOAP (Simple Object Access Protocol) são protocolos de comunicação web e são utilizadas para a troca de informações e dados estruturados através de HTTP/HTTPS. Ao contrário das APIs REST, o SOAP suporta apenas o formato de dados XML. A maior parte da troca de dados na web é realizada através da troca REST, mas isso não significa que o SOAP vá desaparecer em breve, uma vez que é altamente padronizado, mais seguro e, por vezes, permite a automatização.

XML, ou eXtensible Markup Language, é uma ferramenta independente de software ou hardware para armazenar e transportar dados. Possui um conjunto de regras para estruturar mensagens como registos legíveis tanto por humanos como por máquinas. Como poderá ver abaixo, a sua estrutura é semelhante à do HTML, mas a linguagem XML não possui tags predefinidas, pelo que o autor deve definir tanto as tags como a estrutura do documento.

A Representational State Transfer é um estilo de arquitetura criado por Roy Fielding em 2000 para projetar aplicações acopladas sobre HTTP e é frequentemente utilizada no desenvolvimento de APIs. Para que um serviço seja considerado RESTful, não deve violar estas restrições.

Os programadores preferem utilizar REST como alternativa ao SOAP porque não envolve escrever muito código para realizar tarefas simples, ao contrário do SOAP, que exige que se crie a estrutura XML necessária todas as vezes. O serviço web RESTful utiliza uma abordagem diferente. Ele trata a informação como um recurso representado por um URL único. Assim, se quiser solicitar um determinado recurso, terá de fornecer o seu URL utilizando métodos HTTP como GET, POST, PUT, HEAD, DELETE, PATCH e OPTIONS. Pode encontrar mais informações sobre estes métodos aqui! Por vezes, poderá ser necessário enviar dados adicionais juntamente com o URL para obter o que precisa, como uma chave de acesso.

Ao contrário do SOAP, o REST não se limita a utilizar XML para fornecer a resposta. Pode obter a informação em diferentes formatos, como JSON, XML, CSV, texto simples e HTML, que são analisados mais facilmente com base na linguagem que está a utilizar para a sua aplicação.

Aqui está uma comparação entre JSON e XML:

É frequente ouvir os programadores a falar sobre as funcionalidades de diferentes APIs, mas há outro aspeto importante, menos discutido: a documentação. Sem o conhecimento que ela contém, uma API pode muito bem ser um conjunto de hieróglifos.

A documentação de uma API não é um tutorial de videojogo que se pode ignorar com indiferença e aprender a sua mecânica ao longo do caminho. A documentação contém instruções sobre como utilizar e integrar eficazmente a referida API.

Mesmo que uma API seja revolucionária para os programadores, uma documentação fraca ou a falta de conhecimento sobre o seu funcionamento torná-la-ia inútil.

Uma documentação bem escrita pode ajudar a poupar tempo e custos de suporte. A integração de novos utilizadores torna-se mais fácil e estes não precisarão de suporte técnico para utilizar a API. Uma documentação mal escrita pode ser bastante frustrante para os programadores e para a equipa de suporte dos editores.

Algumas documentações podem incluir uma secção de demonstração ou um ambiente de teste onde é possível experimentar funcionalidades e ver resultados em tempo real. Isto ajuda os programadores a visualizar o que a API faz e a compreendê-la melhor.

Espero que o nosso guia «APIs para Leigos» o tenha ajudado a compreender melhor como funcionam as APIs e o quão importantes são no mundo das tecnologias da informação.

O número crescente de aplicações e produtos de software, tanto para uso corporativo como pessoal, necessita de métodos de comunicação e troca de recursos. As APIs satisfazem essa necessidade e são fundamentais para ajudar na expansão da tecnologia.

Dá uma vista de olhos neste artigo sobre APIs de web scraping para veres alguns exemplos de APIs web em ação!