# Diferença entre APIs REST e GraphQL para Consulta de CPF > Entenda as diferenças entre APIs REST e GraphQL para consulta de CPF. Comparação técnica com exemplos práticos e quando usar cada abordagem. **Publicado:** 11/01/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/diferenca-apis-rest-graphql-consulta-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. | Aspecto | REST | GraphQL | |---------|------|---------| | Paradigma | Recursos com URLs fixas | Query language flexível | | Endpoint | Múltiplos (um por recurso) | Único (/graphql) | | Dados retornados | Estrutura fixa definida pelo servidor | Cliente escolhe os campos | | Versionamento | Via URL (/v1/, /v2/) | Evolução contínua do schema | | Caching | HTTP cache nativo (ETag, Cache-Control) | Requer implementação manual | | Overfetching | Comum (retorna todos os campos) | Eliminado por design | - **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. ```bash # 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 # 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 # 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 // 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. | Cenário | Por que REST | Benefício | |---------|-------------|-----------| | API pública | Simplicidade de consumo | Qualquer dev consome em minutos | | Cache agressivo | HTTP cache nativo | Reduz chamadas e custo | | Dados com estrutura fixa | Poucos campos, todos úteis | Sem overfetching na prática | | Documentação | OpenAPI/Swagger maduro | Ferramentas e SDKs automáticos | | Rate limiting | Headers padrão | Retry-After, X-RateLimit | | Monitoramento | Status codes HTTP | Alertas baseados em 4xx/5xx | ```python # 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. | Cenário | Por que GraphQL | Exemplo | |---------|----------------|---------| | Múltiplos recursos relacionados | Uma query busca tudo | CPF + endereço + score em uma chamada | | Frontends diversos | Cada tela pede campos diferentes | App mobile vs painel admin | | Evolução sem versionamento | Campos novos não quebram clientes | Adicionar "email" sem v2 | | Redução de round trips | N consultas viram 1 | Dashboard que combina dados | ```javascript // 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](https://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. ### Leia também - [API de CPF: guia completo de códigos de status e mensagens de erro](https://cpfhub.io/blog/api-de-cpf-guia-completo-de-codigos-de-status-e-mensagens-de-erro) - [API de CPF com cache: como implementar para economizar consultas](https://cpfhub.io/blog/api-de-cpf-com-cache-como-implementar-para-economizar-consultas) - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) - [API de CPF: diferença entre consulta síncrona e assíncrona](https://cpfhub.io/blog/api-de-cpf-diferenca-entre-consulta-sincrona-e-assincrona) --- ## 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](https://www.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`.