O que é API?

O que uma API permite fazer

A API (Application Programming Interface, ou interface de programação de aplicações) define como um programa pode utilizar funções de outro. Ela descreve quais ações estão disponíveis e como o programa deve chamar cada uma. Existem APIs de bibliotecas, de sistemas operacionais e de serviços acessados pela internet.

Imagine um formulário que envia um novo contato para um sistema de atendimento. A API desse sistema pode oferecer uma função de cadastro que exige nome e email. Você configura a integração conforme a documentação, envia os campos no formato esperado e interpreta a resposta para saber se o cadastro foi aceito.

Nesse exemplo, um email obrigatório ausente pode causar a recusa do cadastro. A mensagem devolvida depende da implementação: algumas APIs identificam o campo que precisa de correção, outras retornam uma explicação genérica. Por isso, testar a integração inclui conferir um cadastro válido e observar o comportamento quando falta uma informação obrigatória.

Como funciona o contrato de uma API web

O contrato é a descrição do comportamento que a integração pode esperar. Nas APIs que usam HTTP (Hypertext Transfer Protocol), o programa cliente envia uma requisição ao servidor e recebe uma resposta. O método informa a ação pretendida: GET costuma ser usado para consultar um recurso, e POST pode enviar um cadastro para processamento.

O endereço de acesso, chamado de endpoint, identifica onde a requisição será recebida. Copiar esse endereço para a integração ainda deixa parte da configuração em aberto. A documentação precisa informar, por exemplo, se o nome do contato deve ser enviado no campo name ou no campo nome. Dois campos com o mesmo significado para você podem ser nomes diferentes para o programa que recebe a requisição.

O contrato também define o formato da mensagem, e o JSON (JavaScript Object Notation) é uma possibilidade comum para representar campos e valores. Uma API pode aceitar outros formatos, por isso a integração precisa seguir o formato documentado pelo serviço.

Quando o serviço exige uma credencial, a documentação informa como enviá-la junto da requisição. Conhecer o endereço do serviço não concede permissão para consultar ou alterar os registros.

API, backend e implementação

O backend é a parte da aplicação que executa a lógica no servidor. No exemplo do formulário, ele pode validar o email e gravar o contato no banco. A API define a forma de acessar essa função, permitindo que o formulário use o cadastro sem conhecer as tabelas ou o código que faz a gravação.

Uma alteração interna pode preservar a integração quando mantém o contrato. Trocar a tabela usada para gravar os contatos, por exemplo, não exige necessariamente mudar o formulário. Já remover o campo name e aceitar somente nome exige adaptar as integrações que ainda enviam o nome antigo. Atualizar a documentação explica a mudança, mas o código de cada integração também precisa ser compatível.

Exemplo de cadastro e leitura da resposta

O código 202 Accepted tem outro significado: o servidor aceitou a requisição, mas o processamento pode continuar depois da resposta, como acontece em algumas importações de contatos. Nesse caso, você consulta o acompanhamento previsto pelo serviço para descobrir se a importação terminou ou encontrou erros, pois a aceitação inicial não confirma a criação de todos os contatos.

O que conferir quando a integração falha

Compare a requisição enviada com a chamada descrita na documentação do serviço. Confira o endereço, o método e os nomes dos campos obrigatórios. Quando houver autenticação, verifique se a credencial continua válida e tem permissão para cadastrar.

Leia o código de status junto com o conteúdo da resposta, pois um servidor pode responder e informar que o cadastro foi recusado. Quando a resposta indicar sucesso, confira também o resultado esperado no sistema de destino, especialmente quando houver processamento posterior.

Testar com um contato fictício em ambiente de desenvolvimento permite observar esses comportamentos sem alterar cadastros de clientes. Para examinar a mensagem que a integração envia ao servidor, consulte a explicação sobre a requisição que chama uma API.

Aplicação na formação

Vibe Coding: Do Zero ao MVP

A Formação Vibe Coding acompanha a construção de um sistema de captura de leads. O módulo de APIs conecta o formulário de inscrição ao cadastro e ensina a interpretar a resposta do servidor.

Conhecer a formação →