Leia os conceitos com calma. Cada bloco traz explicações diretas, analogias e checkpoints de aprendizado.
O que é uma API e como funciona o contrato entre sistemas
API (Interface de Programação de Aplicações) é um conjunto de regras que permite que sistemas diferentes conversem entre si. Imagine que você está em um restaurante: a API é o cardápio e o garçom. Você escolhe o prato (endpoint), especifica detalhes (parâmetros), o garçom (protocolo HTTP) leva seu pedido para a cozinha (servidor) e traz a comida pronta (resposta JSON).
Um endpoint é uma URL específica que representa um recurso ou serviço. Os métodos HTTP indicam a ação desejada (ex: GET para obter dados, POST para enviar dados). Parâmetros podem ser enviados na URL (query parameters) ou no corpo da requisição. Headers carregam informações adicionais, como tipo de conteúdo. A resposta inclui um status code que indica sucesso ou erro, e um corpo geralmente em JSON com os dados solicitados.
Exemplo real: Exemplo de endpoint: https://viacep.com.br/ws/01001000/json/ — aqui, '01001000' é o CEP que queremos consultar. O método HTTP é GET, pois queremos obter dados.
Mini caso: Suponha que você queira saber o endereço de um CEP. Você chama a API ViaCEP no endpoint com o CEP desejado. Se o CEP existir, o servidor responde com status 200 e o JSON com o endereço. Se não existir, pode retornar 404, indicando que o recurso não foi encontrado.
Casos de uso comuns:Consultar dados públicos como CEPs, clima, ou informações de usuários.Integrar sistemas internos com serviços externos.Automatizar consultas e atualizações de dados.Construir aplicações que dependem de dados em tempo real.
Erros comuns para evitar:- Confundir endpoint de API com página web comum.
- Ignorar a importância dos parâmetros na URL e seu formato.
- Não verificar o status code antes de processar a resposta.
Checkpoint de compreensão:- Você sabe o que é um endpoint e para que serve?
- Consegue explicar a função dos métodos HTTP?
- Sabe identificar parâmetros na URL e seu papel?
Resumo chave: API é um contrato claro entre quem pede e quem responde. Endpoints são URLs que representam recursos. Métodos HTTP indicam a ação (GET, POST, etc). Parâmetros e headers personalizam a requisição. Status codes indicam sucesso ou erro.
Métodos HTTP principais: foco no GET para consumo de dados
Os métodos HTTP são comandos que indicam a ação que queremos realizar no servidor. Os principais são GET, POST, PUT, DELETE. Para consumo de dados, o método GET é o mais usado, pois solicita informações sem alterar nada no servidor.
GET envia parâmetros na URL, geralmente após o sinal de interrogação (?), chamados query parameters. Por exemplo: https://api.agify.io?name=claudia — aqui, 'name=claudia' é o parâmetro que indica o nome para o qual queremos estimar a idade. O servidor responde com um JSON contendo a informação solicitada.
Exemplo real: Requisição GET para Agify: https://api.agify.io?name=claudia. Resposta JSON: {"name":"claudia","age":45,"count":1234}.
Mini caso: Você quer saber a idade média estimada para o nome 'Claudia'. Faz uma requisição GET para a API Agify com o parâmetro 'name=claudia'. Recebe um JSON com a idade estimada e o número de registros usados para essa estimativa.
Casos de uso comuns:Buscar informações públicas como dados de usuários, endereços, previsões.Testar APIs para entender os dados que retornam.Construir consultas dinâmicas alterando parâmetros na URL.
Erros comuns para evitar:- Enviar parâmetros no corpo da requisição GET (não funciona).
- Esquecer o '?' antes dos parâmetros na URL.
- Não codificar caracteres especiais nos parâmetros.
Checkpoint de compreensão:- Você sabe montar uma URL com query parameters?
- Consegue identificar a diferença entre método GET e POST?
- Sabe interpretar a resposta JSON de uma requisição GET?
Resumo chave: GET é usado para obter dados sem alterar o servidor. Query parameters são enviados na URL após '?' e separados por '&'. A resposta geralmente vem em JSON para fácil interpretação.
Status codes HTTP mais comuns e seu significado
Status codes são números que indicam o resultado da requisição HTTP. Eles ajudam a entender se a chamada foi bem-sucedida ou se houve algum problema.
Os códigos mais comuns são: 200 (OK) — requisição bem-sucedida; 404 (Not Found) — recurso não encontrado; 401 (Unauthorized) — acesso não autorizado. Outros códigos importantes são 400 (Bad Request), 500 (Erro interno do servidor). Sempre verifique o status code antes de processar a resposta para evitar erros.
Exemplo real: Ao consultar um CEP válido na ViaCEP, você recebe status 200 e o JSON com o endereço. Se consultar um CEP inexistente, pode receber status 404, indicando que o recurso não foi encontrado.
Mini caso: Você faz uma requisição para um endpoint que não existe. O servidor responde com status 404. Seu programa deve interpretar isso e tratar o erro, por exemplo, avisando que o dado não está disponível.
Casos de uso comuns:Tratar erros comuns para melhorar a experiência do usuário.Implementar lógica condicional baseada no status code.Detectar problemas de autenticação ou endpoint incorreto.
Erros comuns para evitar:- Ignorar o status code e tentar processar a resposta mesmo com erro.
- Confundir status 404 com erro de conexão.
- Não tratar exceções quando o servidor não responde.
Checkpoint de compreensão:- Você sabe o que significa status 200, 404 e 401?
- Consegue implementar verificação de status code em Python?
- Sabe diferenciar erro de recurso não encontrado e erro de autenticação?
Resumo chave: Status code 200 indica sucesso. Status code 404 indica recurso não encontrado. Status code 401 indica falta de autorização. Sempre verifique o status code antes de usar os dados.
Formato JSON: estrutura, tipos de dados e interpretação
JSON (JavaScript Object Notation) é um formato leve e fácil de ler para troca de dados. Ele representa dados em pares chave-valor, arrays e tipos básicos como strings, números, booleanos e null.
Um objeto JSON é delimitado por chaves { } e contém pares chave:valor. Arrays são listas delimitadas por colchetes [ ]. Exemplos de tipos: string ("texto"), número (123), booleano (true/false), null (valor nulo). Entender a estrutura JSON é essencial para extrair as informações corretas da resposta da API.
Exemplo real: Resposta JSON da ViaCEP: {"cep":"01001-000","logradouro":"Praça da Sé","bairro":"Sé","localidade":"São Paulo","uf":"SP"}. Aqui, cada campo é uma chave com seu valor correspondente.
Mini caso: Você recebe um JSON com dados do endereço. Para mostrar o logradouro, acessa a chave 'logradouro'. Se tentar acessar uma chave que não existe, pode ocorrer erro, então é importante tratar isso no código.
Casos de uso comuns:Extrair informações específicas de respostas de API.Converter JSON para dicionários Python para manipulação.Validar estrutura dos dados recebidos.
Erros comuns para evitar:- Interpretar JSON como texto simples sem parsear.
- Acessar campos que podem não existir sem tratamento.
- Confundir arrays e objetos JSON.
Checkpoint de compreensão:- Você sabe identificar objetos e arrays em JSON?
- Consegue converter JSON em dicionário Python?
- Sabe como acessar valores dentro do JSON com segurança?
Resumo chave: JSON é um formato padrão para troca de dados. Dados são organizados em objetos (chave-valor) e arrays. Tipos básicos incluem string, número, booleano e null. É preciso parsear (converter) JSON para objetos Python.
Usando a biblioteca requests para chamadas HTTP em Python
A biblioteca requests é a forma mais simples e popular para fazer requisições HTTP em Python. Ela permite enviar requisições GET, POST, entre outras, e receber respostas facilmente.
Para fazer uma requisição GET, basta usar requests.get(url). O objeto resposta tem atributos como status_code e método json() para converter o corpo em dicionário Python. Também é possível passar parâmetros via parâmetro params, que monta a URL automaticamente com query parameters.
Exemplo real: Exemplo básico: import requests
response = requests.get('https://viacep.com.br/ws/01001000/json/')
print(response.status_code)
data = response.json()
print(data['logradouro'])
Mini caso: Você quer consultar um CEP e imprimir o logradouro. Faz a requisição, verifica se status_code é 200, então acessa o JSON e imprime o campo desejado. Se o status não for 200, imprime uma mensagem de erro.
Casos de uso comuns:Consumir APIs REST para obter dados externos.Automatizar consultas e integrações.Tratar respostas e erros de forma clara.
Erros comuns para evitar:- Não verificar status_code antes de usar response.json().
- Ignorar exceções como timeout ou conexão falha.
- Montar URLs manualmente sem usar params.
Checkpoint de compreensão:- Você sabe fazer uma requisição GET com requests?
- Consegue acessar status_code e dados JSON da resposta?
- Sabe passar parâmetros usando params?
Resumo chave: requests simplifica chamadas HTTP em Python. Use response.status_code para verificar sucesso. Use response.json() para obter dados em formato Python. Parâmetros podem ser passados via params para GET.
Tratamento básico de erros e exceções na chamada de API
Ao chamar APIs, erros podem acontecer: o servidor pode não responder, o recurso pode não existir, ou a conexão pode falhar. É fundamental tratar essas situações para que seu programa não quebre.
Use try-except para capturar exceções como requests.exceptions.RequestException. Verifique o status_code para identificar erros como 404 ou 401 e trate-os adequadamente, por exemplo, exibindo mensagens amigáveis ou tentando outra ação. Nunca acesse campos JSON sem garantir que a resposta foi bem-sucedida.
Exemplo real: try:
response = requests.get(url)
response.raise_for_status() # levanta erro para códigos 4xx e 5xx
data = response.json()
except requests.exceptions.HTTPError as e:
print(f'Erro HTTP: {e}')
except requests.exceptions.RequestException as e:
print(f'Erro na requisição: {e}')
Mini caso: Você faz uma requisição para um CEP inválido. O servidor retorna 404. Seu código detecta o erro e informa que o CEP não foi encontrado, evitando que o programa tente acessar dados inexistentes.
Casos de uso comuns:Construir aplicações robustas que lidam com falhas.Melhorar a experiência do usuário com mensagens úteis.Garantir que dados inválidos não causem erros no programa.
Erros comuns para evitar:- Não usar try-except e deixar o programa quebrar.
- Ignorar status_code e processar respostas inválidas.
- Não informar o usuário sobre erros ocorridos.
Checkpoint de compreensão:- Você sabe implementar tratamento básico de exceções?
- Consegue diferenciar erros HTTP de erros de conexão?
- Sabe como informar erros para o usuário final?
Resumo chave: Trate exceções para evitar crashes. Verifique status_code antes de usar dados. Use mensagens claras para informar erros. Nunca assuma que a resposta é sempre válida.