Programação · conceitos · web

O que é uma API?

Ouve-o constantemente: « chamar a API », « a API pública », « uma chave de API ». Uma API (Application Programming Interface) é uma das ideias mais úteis do software — e uma das mais carregadas de jargão. Este guia explica, de forma simples, o que é uma API, os principais tipos com que se vai deparar, como funciona um pedido típico a uma API web e porque é que as APIs estão em todo o lado.

A definição curta

Uma API é um contrato que permite a um software comunicar com outro. Define que pedidos pode fazer, que dados deve enviar e o que recebe em troca — sem que precise de saber como o outro lado está construído internamente.

A analogia clássica é o restaurante. Você (um programa) lê uma ementa (a API) e faz um pedido ao empregado de mesa. Não entra na cozinha nem precisa de saber como o prato é preparado. A ementa é a interface acordada; a cozinha é a implementação, escondida por trás. Uma API é essa ementa para o software.

Os principais tipos de API

• API web (as mais discutidas) — um programa fala com outro através da rede, normalmente via HTTP. Quando uma app de meteorologia mostra a previsão, chama a API web de um serviço meteorológico. A maioria das APIs web modernas segue o estilo REST e troca dados em JSON (ver REST vs GraphQL e gRPC vs REST para as principais alternativas).
• API de biblioteca / framework — o conjunto de funções e tipos que uma biblioteca de código expõe para que os chame. Quando usa uma biblioteca de datas, as funções que ela lhe oferece são a sua API.
• API do sistema operativo — a forma como um programa pede ao sistema operativo para abrir um ficheiro, desenhar uma janela ou usar a rede. O POSIX é uma delas.

O fio condutor: uma API é a superfície publicada de algo, a parte que tem o direito de usar, separada dos mecanismos internos dos quais não deve depender.

Como funciona um pedido a uma API web

Uma chamada a uma API web é um pedido e uma resposta. O cliente envia um pedido HTTP a um URL (um endpoint) usando um método que sinaliza a sua intenção, e o servidor devolve um código de estado e, normalmente, dados. Os métodos comuns:

• GET — ler dados (« dá-me o utilizador 42 »).
• POST — criar algo novo.
• PUT / PATCH — atualizar algo.
• DELETE — eliminar algo.

Um pedido simples para ler um utilizador poderia parecer-se com isto, com o servidor a responder em JSON:

GET /users/42  HTTP/1.1
Host: api.example.com

-- response --
200 OK
{ "id": 42, "name": "Ada", "active": true }

O 200 é um código de estado que significa sucesso; 404 significa não encontrado, 401 não autenticado, 500 um erro do servidor. O corpo é JSON — o formato leve e legível por humanos que a maioria das APIs web usa para trocar dados estruturados.

Autenticação e chaves

Muitas APIs exigem que se identifique com uma chave de API ou um token, enviado num cabeçalho do pedido. Isto permite ao fornecedor controlar quem usa o serviço, aplicar limites de taxa e cobrar a utilização. Mantenha as chaves secretas — uma chave divulgada é como uma palavra-passe divulgada.

Porque é que as APIs importam

As APIs são o que permite compor o software em vez de o reconstruir. Uma loja pode cobrar pagamentos sem escrever um banco; uma app pode mostrar um mapa sem desenhar o mundo; os serviços de uma mesma empresa falam entre si através de APIs internas. Transformam as capacidades dos outros em blocos que chama com poucas linhas — e isso é, no essencial, a forma como o software moderno se constrói.

Os limites honestos

Uma API é uma dependência. Se o fornecedor a alterar, o limitar na taxa, aumentar os preços ou encerrar, o seu software é afetado — por isso é que as boas APIs são versionadas e documentadas, e por isso é que trata erros e tempos limite em vez de assumir que cada chamada tem sucesso. Uma API esconde a complexidade; não a elimina.

Em resumo

Uma API é um contrato que permite a um programa usar as capacidades de outro através de um conjunto definido de pedidos e respostas, sem tocar nos seus mecanismos internos. As APIs web/REST sobre HTTP com JSON são o tipo com que mais se irá deparar, mas a ideia — uma interface publicada, separada da implementação subjacente — atravessa bibliotecas, sistemas operativos e qualquer programa bem estruturado. Aprenda a ler a documentação de uma API e poderá ligar quase tudo a tudo.

Novo numa linguagem para construir ou chamar APIs? Percorra o nosso índice de guias para explicações de programação claras e originais.