GraphQL API — Destaques Gov.BR¶
API GraphQL unificada do Destaques Gov.BR. É a fachada de dados única entre os consumidores da plataforma (portal Next.js, workers de dados) e os backends de persistência (Firestore, PostgreSQL, Typesense). Substitui a colcha de retalhos anterior, em que o portal e os workers falavam direto com cada backend via REST/Firebase Admin/SQL.
flowchart LR
portal[Portal Next.js] -->|HTTP + JWT| api
workers[Workers de dados] -->|HTTP + OIDC| api
embed[Widgets embarcáveis] -->|HTTP público| api
api[graphql-api<br/>Strawberry + FastAPI] --> fs[(Firestore)]
api --> pg[(PostgreSQL<br/>govbrnews)]
api --> ts[(Typesense)]Por que uma fachada GraphQL¶
- Desacoplamento. Os consumidores deixam de conhecer o formato dos backends. Trocar Firestore por outra coisa, ou mudar o JOIN do Postgres, não vaza para o portal nem para os workers. O portal já consome o graphql-api como fonte única tanto para conteúdo público (artigos, busca, temas, relacionados, contagens) quanto para as features (clipping/marketplace, releases, telegram) — sem acesso direto a Firestore/Typesense nessas superfícies.
- Schema tipado e único. Um contrato versionado, introspectável, com um único ponto de evolução. A referência é gerada do código.
- Auth centralizada. Validação de JWT (usuários) e OIDC (service accounts) em um lugar só, com permissões declarativas por campo.
Stack¶
| Camada | Tecnologia |
|---|---|
| Schema | Strawberry GraphQL (code-first, Python 3.12) |
| HTTP | FastAPI + Uvicorn |
| Subscriptions | SSE via /graphql/stream (graphql-sse) |
| Deploy | Cloud Run (destaquesgovbr-graphql-api), env vars via Terraform |
| Datasources | asyncpg (Postgres), firebase-admin (Firestore), typesense-python |
| Auth | PyJWT + JWKS do Keycloak; OIDC via metadata server / ADC |
Playground interativo
A API serve o GraphiQL nativo em GET /graphql — explore o schema,
autocomplete e rode queries no browser, sem instalar nada:
playground de staging
· localmente em http://localhost:8000/graphql. Ver
Exemplos › Playground.
Mapa da documentação¶
- Arquitetura — visão de componentes, code-first, CORS, healthcheck.
- Datasources — Firestore/Postgres/Typesense, DataLoaders, async vs sync.
- Autenticação — JWT de usuário e OIDC de service account.
- Subscriptions & SSE — o agente de recortes em tempo real.
- Exemplos — queries e mutations reais, com os gotchas.
- Referência: Schema (SDL) — SDL completo, gerado do código.
Documentação central
Esta é a documentação profunda do serviço, versionada junto do código. A visão de alto nível e o lugar do serviço na plataforma estão na documentação central do DGB (módulo GraphQL API).