Working with JSON APIs: A Beginner's Guide — csv-x.com

Eu ainda me lembro do dia em que acidentalmente derrubei todo o pipeline de dados da nossa empresa. Era 2015, eu estava há três meses no meu primeiro emprego como desenvolvedor júnior em uma startup de fintech, e havia acabado de enviar um código que fez 50.000 solicitações de API em menos de dois minutos. Nosso limite de taxa era de 1.000 por hora. As ligações do nosso provedor de API não foram agradáveis, e a conversa com meu CTO também não. Esse momento embaraçoso me ensinou mais sobre como trabalhar com APIs JSON do que qualquer tutorial já poderia, e é por isso que estou escrevendo este guia hoje—para que você possa aprender com meus erros em vez de cometer os seus.

Nos últimos nove anos como engenheiro de backend e especialista em integração de API, trabalhei com centenas de APIs JSON diferentes—desde serviços de clima simples até fornecedores de dados financeiros complexos. Construí sistemas que processam milhões de chamadas de API diariamente, e depurei problemas de integração que custaram às empresas milhares de dólares por hora de inatividade. O que aprendi é que trabalhar com APIs JSON não se trata apenas de fazer solicitações HTTP e analisar respostas. É sobre entender limites de taxa, lidar com erros de forma elegante, gerenciar autenticação de forma segura e construir sistemas resilientes que não desmoronem quando as coisas dão errado.

Este guia o levará por tudo o que você precisa saber para trabalhar com confiança com APIs JSON, seja você construindo sua primeira integração ou procurando aprimorar suas habilidades. Vamos cobrir os fundamentos, explorar armadilhas comuns e mergulhar em técnicas práticas que o tornarão um desenvolvedor mais eficaz.

Entendendo o que são realmente as APIs JSON

Antes de mergulharmos nos detalhes técnicos, vamos estabelecer sobre o que estamos realmente falando. Uma API JSON é simplesmente uma forma de diferentes aplicativos de software se comunicarem entre si pela internet usando JSON (JavaScript Object Notation) como formato de dados. Pense nisso como um garçom em um restaurante—você (o cliente) faz um pedido por algo específico, o garçom leva esse pedido para a cozinha (o servidor) e traz de volta exatamente o que você pediu em um formato padronizado.

JSON se tornou o formato dominante para APIs web porque é leve, legível por humanos e suportado por praticamente todas as linguagens de programação. Quando comecei minha carreira, XML ainda era comum, e deixe-me dizer—trabalhar com JSON é infinitamente mais agradável. Uma resposta JSON típica pode parecer assim:

{"user": {"id": 12345, "name": "Sarah Chen", "email": "[email protected]", "created_at": "2024-01-15T10:30:00Z"}}

Compare isso com o equivalente em XML, com todas as suas tags de abertura e fechamento, e você entenderá porque o JSON venceu. É conciso, fácil de ler e se mapeia naturalmente para estruturas de dados na maioria das linguagens de programação—objetos em JavaScript, dicionários em Python, mapas em Go, e assim por diante.

As modernas APIs JSON seguem em sua maioria os princípios REST (Representational State Transfer), o que significa que utilizam métodos HTTP padrão como GET (recuperar dados), POST (criar dados), PUT ou PATCH (atualizar dados) e DELETE (remover dados). Essa padronização torna as APIs previsíveis e mais fáceis de trabalhar. Quando você vê uma solicitação GET para /api/users/12345, pode razoavelmente supor que está buscando informações sobre o usuário 12345. Um POST para /api/users provavelmente está criando um novo usuário.

Entender essa base é crucial porque molda como você interagirá com praticamente toda API que encontrar. Os padrões são consistentes entre diferentes serviços, o que significa que uma vez que você domina o básico com uma API, pode aplicar esse conhecimento a centenas de outras.

Fazendo sua primeira solicitação de API

Vamos ser práticos. A maneira mais simples de interagir com uma API JSON é através de uma ferramenta como curl ou Postman, mas eventualmente você vai querer fazer solicitações a partir do seu código. Vou mostrar exemplos em Python já que é amplamente acessível, mas os conceitos se aplicam a qualquer linguagem.

Aqui está a solicitação de API mais básica que você pode fazer:

import requests
response = requests.get('https://api.example.com/users/12345')
data = response.json()
print(data['name'])

Esse trecho de quatro linhas faz muito: envia uma solicitação HTTP GET para a API, recebe a resposta, analisa o JSON em um dicionário Python e extrai um campo específico. Simples, certo? Mas esse código tem pelo menos cinco problemas sérios que o fariam falhar em produção.

Primeiro, não há tratamento de erros. O que acontece se a rede estiver fora? E se o usuário não existir e a API retornar um 404? E se a API estiver temporariamente indisponível e retornar um 503? Seu código vai falhar. Segundo, não há um tempo limite especificado. Se o servidor da API travar, seu código vai esperar indefinidamente. Terceiro, não há autenticação—maioria das APIs reais requer algum tipo de credenciais. Quarto, não há consideração sobre limitação de taxa. E quinto, não há validação de que a resposta realmente contém os dados que você espera.

Aqui está uma versão mais robusta que resolve esses problemas:

import requests
from requests.exceptions import RequestException
import time

def fetch_user(user_id, api_key, max_retries=3):
    url = f'https://api.example.com/users/{user_id}'
    headers = {'Authorization': f'Bearer {api_key}'}
    
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers, timeout=10)
            response.raise_for_status()
            data = response.json()
            
            if 'name' not in data:
                raise ValueError('Formato de resposta inválido')
            
            return data
        
        except RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 attempt)
    
    return None