Guias

Uma API REST é a forma mais comum de uma peça de software comunicar com outra através da web. REST significa REpresentational State Transfer — um conjunto de convenções para pedir e alterar dados usando os métodos web (HTTP) habituais. Sempre que uma aplicação vai buscar o seu perfil ou publica um comentário, está quase de certeza a chamar uma API REST nos bastidores.

Como funciona uma API REST

A ideia central é simples: tudo é um «recurso» com o seu próprio URL, e age-se sobre ele com verbos HTTP padrão. O GET lê dados, o POST cria-os, o PUT ou o PATCH atualiza-os, e o DELETE remove-os. Peça GET /users/42 e obtém o utilizador 42; envie DELETE /users/42 e esse utilizador desaparece.

O servidor responde com dados, quase sempre em JSON — um formato leve e legível por humanos. Cada resposta traz também um código de estado, como 200 OK, 404 Not Found ou 401 Unauthorized, que diz à sua aplicação exatamente o que aconteceu para que ela possa reagir corretamente.

Porque os programadores usam REST

O REST é também «sem estado» (stateless): cada pedido carrega tudo o que o servidor precisa, e o servidor não guarda memória de chamadas anteriores. Isso torna as API REST fáceis de escalar, porque qualquer servidor consegue tratar qualquer pedido — uma das grandes razões pela qual este estilo se tornou o padrão em toda a web.

• Permite que um software comunique com outro através de HTTP
• Os recursos têm URLs; os verbos são GET, POST, PUT, DELETE
• As respostas são normalmente JSON com um código de estado
• Sem estado — cada pedido é autónomo, por isso escala
• Protegida com tokens (chave de API ou JWT) sobre HTTPS

Para os programadores de front-end, o REST é trabalho do dia a dia. A sua aplicação Vue, React ou em JavaScript puro vai buscar dados a endpoints REST (usando fetch ou uma biblioteca como o axios), apresenta-os na página, e devolve as alterações. A API é o contrato entre a sua interface e os dados que estão por trás dela.

REST vs GraphQL

O REST não é a única opção. O GraphQL permite ao cliente pedir exatamente os campos que quer num único pedido, o que pode reduzir o excesso de dados obtidos. Mas a simplicidade do REST, a facilidade de cache e a sua pura ubiquidade mantêm-no, com larga vantagem, o estilo de API mais utilizado.

Segurança e bom design

As API reais precisam de controlo de acesso. A maioria envia um token — uma chave de API ou um JWT — num cabeçalho do pedido, e funciona sobre HTTPS para que os dados não possam ser lidos em trânsito. As API bem geridas também versionam os seus endpoints (/v1/, /v2/) para que as alterações não quebrem de repente as aplicações que já as usam.

Uma API REST bem concebida é previsível: URLs de recursos claros, os verbos HTTP e códigos de estado certos, JSON consistente, e mensagens de erro úteis. É essa previsibilidade que permite que um front-end e um back-end sejam construídos por pessoas diferentes e ainda assim encaixem bem um no outro.

Onde corre uma API REST

Por fim, uma API REST tem de correr algures. O seu front-end pode ser ficheiros estáticos servidos a partir de um CDN, mas a própria API precisa de um servidor real, sempre ativo, para tratar dos pedidos e aceder à sua base de dados. Em suma: uma API REST é o contrato padrão da web para mover dados entre programas — simples, sem estado, JSON sobre HTTP — e é um servidor fiável que a mantém a responder.