Diferença entre APIs REST e GraphQL para Consulta de CPF

Para consulta de CPF, REST é a escolha mais adequada na maioria dos cenários: a API do CPFHub.io segue esse padrão, oferecendo um endpoint único (GET https://api.cpfhub.io/cpf/{CPF}) com autenticação via header x-api-key, estrutura de resposta fixa e compatibilidade nativa com cache HTTP — enquanto GraphQL, embora poderoso para dados interconectados, adiciona complexidade desnecessária para consultas simples com campos predefinidos.

Introdução

Ao projetar ou consumir uma API de consulta de CPF, duas arquiteturas dominam o cenário: REST e GraphQL. Cada uma tem filosofias distintas sobre como estruturar requisições, retornar dados e evoluir a API ao longo do tempo. A API do CPFHub.io segue o padrão REST, que é a escolha mais comum para APIs de dados públicos, mas entender as diferenças ajuda a tomar decisões informadas sobre a arquitetura do seu sistema.

Conceitos fundamentais de cada abordagem

REST e GraphQL diferem na forma como o cliente solicita e recebe dados.

• REST — cada recurso tem uma URL única e o servidor define quais campos retornar
• GraphQL — um único endpoint aceita queries que especificam exatamente quais dados o cliente precisa
• Overfetching — quando a API retorna mais dados do que o cliente precisa, desperdiçando banda

Consulta de CPF: REST vs GraphQL na prática

Veja como a mesma consulta de CPF seria feita em cada paradigma.

# REST - Requisição simples e direta
curl -X GET "https://api.cpfhub.io/cpf/12345678909" \
    -H "x-api-key: sua-chave-aqui"

# Resposta REST (estrutura fixa)
{
    "success": true,
    "data": {
    "cpf": "12345678909",
    "name": "João da Silva",
    "nameUpper": "JOÃO DA SILVA",
    "gender": "M",
    "birthDate": "01/01/1990",
    "day": "01",
    "month": "01",
    "year": "1990"
    }
}

# GraphQL - Cliente escolhe os campos
query {
    consultarCPF(cpf: "12345678909") {
    name
    birthDate
    gender
    }
}

# Resposta GraphQL (apenas campos solicitados)
{
    "data": {
    "consultarCPF": {
    "name": "João da Silva",
    "birthDate": "01/01/1990",
    "gender": "M"
    }
    }
}

• REST retorna tudo — todos os campos do recurso vêm na resposta, mesmo que você precise apenas do nome
• GraphQL retorna sob demanda — o cliente especifica exatamente quais campos precisa na query
• Simplicidade vs flexibilidade — REST é mais simples de consumir, GraphQL é mais eficiente em bandwidth

Implementando o consumo em ambos os paradigmas

Compare o código necessário para consumir cada tipo de API em Python e JavaScript.

# Python - Consumindo REST
import requests

def consultar_cpf_rest(cpf: str) -> dict:
    response = requests.get(
    f"https://api.cpfhub.io/cpf/{cpf}",
    headers={"x-api-key": "sua-chave-aqui"}
    )
    response.raise_for_status()
    dados = response.json()
    return {
    "nome": dados["data"]["name"],
    "nascimento": dados["data"]["birthDate"],
    }

# Python - Consumindo GraphQL (hipotético)
def consultar_cpf_graphql(cpf: str) -> dict:
    query = """
    query ConsultarCPF($cpf: String!) {
    consultarCPF(cpf: $cpf) {
    name
    birthDate
    }
    }
    """
    response = requests.post(
    "https://api.exemplo.io/graphql",
    json={"query": query, "variables": {"cpf": cpf}},
    headers={"Authorization": "Bearer token-aqui"}
    )
    response.raise_for_status()
    return response.json()["data"]["consultarCPF"]

// JavaScript - Consumindo REST
async function consultarCPFRest(cpf) {
    const response = await fetch(
    `https://api.cpfhub.io/cpf/${cpf}`,
    { headers: { "x-api-key": "sua-chave-aqui" } }
    );
    const dados = await response.json();
    return { nome: dados.data.name, nascimento: dados.data.birthDate };
}

// JavaScript - Consumindo GraphQL (hipotético)
async function consultarCPFGraphQL(cpf) {
    const query = `
    query ConsultarCPF($cpf: String!) {
    consultarCPF(cpf: $cpf) {
    name
    birthDate
    }
    }
    `;
    const response = await fetch("https://api.exemplo.io/graphql", {
    method: "POST",
    headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer token-aqui",
    },
    body: JSON.stringify({ query, variables: { cpf } }),
    });
    const dados = await response.json();
    return dados.data.consultarCPF;
}

• REST usa GET — método HTTP semântico para leitura de recursos, compatível com cache do browser
• GraphQL usa POST — todas as operações são POST com a query no body, impossibilitando cache HTTP
• Variáveis GraphQL — evitam concatenação de strings e previnem injection attacks

Quando REST é a melhor escolha para CPF

Para APIs de consulta de CPF, REST oferece vantagens significativas em cenários específicos.

# REST - Cache HTTP nativo aproveitado automaticamente
import requests
from requests_cache import CachedSession

session = CachedSession(
    "cpf_cache",
    expire_after=3600,
    allowable_methods=["GET"],
)

def consultar_com_cache(cpf: str) -> dict:
    response = session.get(
    f"https://api.cpfhub.io/cpf/{cpf}",
    headers={"x-api-key": "sua-chave-aqui"}
    )
    print(f"Do cache: {response.from_cache}")
    return response.json()

• Cache HTTP — respostas GET podem ser cacheadas pelo browser, CDN e proxy automaticamente
• Status codes — códigos padronizados facilitam tratamento de erros e monitoramento
• Simplicidade — nenhuma biblioteca adicional necessária, curl ou fetch são suficientes

Quando GraphQL pode fazer sentido

Embora REST seja ideal para consulta de CPF, GraphQL brilha em cenários com dados interconectados.

// GraphQL - Múltiplos recursos em uma query (hipotético)
const query = `
    query DadosCompletos($cpf: String!) {
    pessoa(cpf: $cpf) {
    name
    birthDate
    enderecos {
    rua
    cidade
    estado
    }
    scoreCredito {
    valor
    classificacao
    }
    }
    }
`;
// Uma única requisição retorna CPF + endereços + score

• N+1 problem — GraphQL resolve naturalmente o problema de múltiplas chamadas para dados relacionados
• Schema tipado — o schema GraphQL funciona como documentação e contrato automaticamente
• Introspecção — clientes podem descobrir a API programaticamente via queries de schema

A especificação completa do GraphQL está disponível em graphql.org/learn, com guias sobre queries, mutations e schema definition language.

Perguntas frequentes

Por que a API do CPFHub.io usa REST e não GraphQL?

REST é a escolha natural para APIs de consulta de dados com estrutura fixa e poucas variações. O endpoint GET https://api.cpfhub.io/cpf/{CPF} retorna sempre os mesmos campos, o que elimina a principal vantagem do GraphQL (seleção de campos). Além disso, REST permite cache HTTP nativo — reduzindo latência e custo — enquanto GraphQL exigiria implementação manual de caching.

É possível usar GraphQL para consumir a API do CPFHub.io?

Não diretamente — a API do CPFHub.io é REST. Mas você pode criar uma camada GraphQL própria que internamente chama a API REST do CPFHub.io. Isso faz sentido se você tem um backend GraphQL existente e quer expor dados de CPF junto com outros recursos do seu sistema em uma única query.

Qual o impacto da escolha REST vs GraphQL na latência de consulta de CPF?

Para consultas simples de CPF, REST tende a ser mais rápido na prática: menos overhead de parsing da query, compatibilidade nativa com CDN e HTTP cache, e nenhuma resolução de schema. A latência da API do CPFHub.io é de aproximadamente 900ms; implementar GraphQL não reduz esse tempo, mas pode reduzir o número de round trips se você combinar múltiplos recursos em uma consulta.

Como tratar erros em REST vs GraphQL ao consultar CPF?

Em REST, erros são comunicados via status codes HTTP (400 para CPF inválido, 401 para key inválida, 404 para CPF não encontrado). Em GraphQL, mesmo erros retornam HTTP 200 com um campo errors no body — o que exige lógica adicional de tratamento. Para a API do CPFHub.io (REST), verifique sempre response.success além do status HTTP para distinguir um CPF não encontrado de um erro de autenticação.

Conclusão

Para consulta de CPF, REST é a escolha mais adequada na maioria dos cenários. A simplicidade, o cache HTTP nativo, os status codes padronizados e a facilidade de consumo fazem do REST a arquitetura ideal para APIs de dados com estrutura fixa. GraphQL brilha em cenários com dados interconectados e frontends diversos, mas adiciona complexidade desnecessária para consultas simples.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e integre a API REST de CPF ao seu sistema com um simples GET e o header x-api-key.