O Que É uma API e Como Se Usa no Desenvolvimento Web

O que é uma API

Uma API (Application Programming Interface) é um conjunto de regras e protocolos que permite que diferentes aplicações de software comuniquem entre si. Imagine uma API como um empregado de mesa num restaurante, que transmite os seus pedidos à cozinha e lhe traz os pratos prontos. Não precisa de saber como funciona a cozinha, porque a API trata de tudo entre o seu pedido e o resultado que recebe de volta.

No contexto do desenvolvimento web, uma API permite que o frontend comunique com o backend, que as aplicações móveis acedam à mesma base de dados que o site e que diferentes serviços troquem dados entre si. Sem APIs, cada aplicação teria de fazer tudo por si própria, ao passo que com APIs podemos usar serviços especializados para pagamentos, envio de email, previsão meteorológica, mapas e centenas de outras funcionalidades.

Tipos de API

• REST API — o tipo mais comum, usa métodos HTTP (GET, POST, PUT, DELETE)
• GraphQL — mais flexível, o cliente escolhe exatamente os dados que pretende
• SOAP — norma mais antiga, usa XML, comum na banca e nos seguros
• WebSocket API — comunicação bidirecional em tempo real
• gRPC — protocolo binário rápido, popular na arquitetura de microsserviços

REST API — a norma moderna da web

REST (Representational State Transfer) é um estilo arquitetural que usa métodos HTTP padrão. Para projetos com APIs, considere um plano VPS mais avançado para a comunicação. A REST API é de longe o tipo de API mais popular na web atualmente, devido à sua simplicidade e amplo suporte. Cada recurso no servidor tem o seu próprio endereço URL, e o cliente acede a esses recursos através de métodos HTTP padrão.

O princípio REST implica que cada pedido é independente e que o servidor não guarda estado entre pedidos. Isto torna as REST APIs escaláveis, porque os pedidos podem ser distribuídos por vários servidores sem preocupações com sessões. As respostas são normalmente em formato JSON, que é fácil de ler e processar em qualquer linguagem de programação.

Métodos HTTP na REST API

Os quatro métodos HTTP básicos em REST correspondem às operações CRUD, que são a base de qualquer aplicação que trabalhe com dados.

• GET — leitura de dados (por exemplo, GET /api/users devolve a lista de utilizadores)
• POST — criação de um novo recurso (por exemplo, POST /api/users cria um novo utilizador)
• PUT — atualização de um recurso existente (por exemplo, PUT /api/users/1 atualiza o utilizador com o ID 1)
• DELETE — eliminação de um recurso (por exemplo, DELETE /api/users/1 elimina o utilizador)

Endpoints — os endereços dos recursos da API

Um endpoint é um endereço URL específico onde vive um recurso da API. Endpoints bem concebidos são intuitivos e seguem uma convenção de nomenclatura clara. Usam-se substantivos no plural para os recursos e uma estrutura hierárquica para os recursos relacionados. Por exemplo, /api/users para todos os utilizadores, /api/users/42 para um utilizador específico e /api/users/42/orders para as encomendas desse utilizador.

A organização dos endpoints é fundamental para a usabilidade da API. O versionamento através do URL, como /api/v1/users, permite introduzir alterações sem quebrar as integrações existentes. A filtragem, ordenação e paginação são implementadas através de parâmetros de consulta, como /api/users?role=admin&sort=name&page=2. Uma boa documentação dos endpoints é tão importante como o próprio código, porque os programadores que usam a sua API têm de compreender facilmente como ela funciona.

Formato JSON

JSON (JavaScript Object Notation) é o formato padrão para a troca de dados na comunicação por API. É legível tanto para humanos como para máquinas, o que o torna ideal para depuração e desenvolvimento. O JSON suporta tipos de dados básicos como strings, números, valores booleanos, arrays e objetos, o que é suficiente para representar quase qualquer estrutura de dados.

Uma resposta JSON típica de uma API contém os dados solicitados, juntamente com metainformação sobre o estado do pedido, a paginação e eventuais erros. A estrutura da resposta deve ser consistente em toda a API, para que o cliente saiba sempre o que esperar. Comprimir as respostas JSON através de gzip reduz a quantidade de dados transferidos e acelera a comunicação, especialmente nas redes móveis.

Exemplo de resposta JSON

Quando solicita uma lista de produtos através de GET /api/products, o servidor devolve uma resposta JSON estruturada que contém um array de objetos com dados sobre cada produto. Cada objeto tem campos como id, name, price, description e category. A resposta inclui também informação sobre o número total de resultados e a página para paginação, para que o cliente saiba se há mais dados para carregar.

Autenticação e segurança

A autenticação da API é o processo de verificar a identidade do cliente que envia o pedido. Sem autenticação, qualquer pessoa poderia aceder aos seus dados ou executar ações em nome dos seus utilizadores. Existem vários métodos de autenticação comuns, cada um com as suas vantagens e aplicação em diferentes cenários.

Métodos de autenticação

• Chave de API — string simples enviada com cada pedido, boa para comunicação entre servidores
• Bearer Token (JWT) — JSON Web Token que contém informação codificada do utilizador, padrão para aplicações web e móveis
• OAuth 2.0 — protocolo mais complexo que permite o acesso de terceiros sem partilhar a palavra-passe, usado pela Google, Facebook e outros
• Basic Auth — nome de utilizador e palavra-passe codificados em Base64, usado apenas com HTTPS

Práticas de segurança

Use sempre uma ligação HTTPS encriptada para a comunicação por API, porque sem encriptação os dados, incluindo tokens e palavras-passe, viajam em texto simples. Implemente rate limiting para impedir abusos, porque sem restrições um atacante pode enviar milhões de pedidos e fazer colapsar o seu servidor. As definições de CORS controlam quais os domínios que podem aceder à sua API a partir de um navegador, uma proteção importante contra integrações não autorizadas.

Exemplos práticos de utilização de APIs

As APIs estão por todo o lado à nossa volta, mesmo quando não nos apercebemos, desde o sistema DNS aos processadores de pagamento. Quando vê um Google Map num site, isso é a API do Google Maps. Quando paga com cartão online, o site comunica com a API do processador de pagamentos. Quando inicia sessão através de uma conta Google ou Facebook, é usada a API OAuth. A previsão meteorológica no seu telemóvel vem da API do serviço meteorológico.

APIs comuns no desenvolvimento web

• API do Stripe ou do PayPal para pagamentos online
• API do SendGrid ou do Mailgun para envio de emails
• API do Google Maps para mapas e geolocalização
• API do Twilio para SMS e chamadas telefónicas
• API do Firebase para bases de dados em tempo real e autenticação
• API do Cloudinary para otimização e transformação de imagens

Como começar a usar APIs

A melhor forma de aprender APIs é começar por APIs públicas simples que não exigem autenticação. Use ferramentas como o Postman ou o Insomnia para enviar pedidos e ver respostas sem escrever código. Depois, passe para a integração no seu projeto, usando fetch ou axios em JavaScript, ou as bibliotecas HTTP adequadas noutras linguagens.

A documentação é a sua melhor amiga quando trabalha com APIs. As APIs de qualidade têm documentação detalhada, com exemplos de pedidos e respostas para cada endpoint. A especificação Swagger ou OpenAPI é a norma para documentar REST APIs e também permite a geração automática de código do cliente. Comece devagar, experimente, e em breve considerará as integrações de APIs uma parte rotineira do desenvolvimento web.