API de consulta REST: contrato conhecido, uso bloqueado

Selo de estado: Preview (teto atual do produto) · Curso ACD-250 — Integrações e consumo externo · Aula 6 de 6 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai justificar por que não construir sobre ela hoje — com o contrato na mão, o motivo do bloqueio e a alternativa que está disponível.

Vídeo#

Identificador no manifesto: acd-250-06-api-rest-o-que-nao-usar-ainda · duração-alvo 5 min · tela do produto: /connect.

Roteiro de gravação (5 capítulos):

#	Minutagem-alvo	Capítulo	Tela do produto
1	0:00–0:30	Abertura: título + selo. Documentar sem liberar é transparência, não convite.	`/connect`
2	0:30–1:45	O contrato: `GET /api/v1/tables`, `GET /api/v1/tables/{dataset}/{table}`, `POST /api/v1/query`.	`/connect`
3	1:45–3:00	Por que está fora de GA: rota cobrável + limitador fail-closed a re-provar + proteção de custo.	`/connect`
4	3:00–4:15	As defesas que já existem (cinco camadas antes de tocar o BigQuery) — e por que elas não bastam para liberar.	`/connect`
5	4:15–5:00	A alternativa disponível: feed OData. Erros comuns e encerramento do curso.	`/excel`

Conteúdo#

Esta aula fecha o curso com o caso mais delicado e o mais formativo: uma capacidade que existe no código, está documentada em detalhe e você não deve usar. A API de consulta REST — GET /api/v1/tables e POST /api/v1/query — está fora de GA: indisponível para uso externo hoje.

Vale dizer o que "fora de GA" significa aqui, porque não é Roadmap nem Preview. Roadmap é o que não existe. Preview é o que funciona sem SLA e você pode usar por sua conta e risco. Fora de GA é o terceiro caso: o código está lá, o contrato está escrito, e a liberação foi retida de propósito. A documentação existe para planejamento e transparência — não para você começar a construir.

O contrato, em três rotas

Rota	O que faz	Observação
`GET /api/v1/tables`	lista as tabelas dos marts publicados (gold + silver), com colunas e tipos	custo R$ 0 — listar catálogo não dispara job pago
`GET /api/v1/tables/{dataset}/{table}?limit=&offset=`	linhas paginadas de uma tabela publicada	`limit` padrão 100, máximo 1000; resposta traz `nextOffset`
`POST /api/v1/query`	SQL somente leitura (`SELECT` / `WITH … SELECT`) escopado ao workspace	corpo `{ "sql": …, "limit"? : … }`; resposta `{ rows, rowCount }`

Se um resultado for cortado por segurança, a resposta inclui "truncated": true e "totalRows" — para a soma do outro lado não sair errada em silêncio. É a mesma filosofia do 501 do OData: falhar em voz alta é melhor que entregar número errado.

Por que está retida

O motivo é um, e é econômico: são rotas que disparam consulta cobrável no BigQuery. Um SQL livre vindo de fora, sem teto comprovado, é uma fatura sem teto. A liberação depende de duas evidências que ainda não estão fechadas: a guarda de limite de requisições em modo fail-closed re-provada de forma independente (negar quando o limitador estiver indisponível, como a Aula 5 descreveu) e o gate de capacidade da API com a proteção de custo endurecida.

No registro de claims do produto, isso aparece explicitamente: "/api/v1 como disponível/GA" está barrado por evidência pendente. Não é um atraso de documentação — é uma decisão de não prometer o que não foi medido.

Não construa sobre estas rotas hoje

Enquanto estiver fora de GA, uma integração sobre /api/v1/query ou /api/v1/tables deve tratar respostas de indisponibilidade (503) como estado esperado, não como incidente. O contrato pode mudar sem a garantia de compatibilidade que as superfícies Preview oferecem. Em outras palavras: dá para ler a doc, dá para planejar — não dá para prometer a um cliente.

As defesas que já existem (e por que não bastam)

Vale conhecê-las, porque elas explicam o que não é o motivo do bloqueio. Antes de tocar o BigQuery, o POST /api/v1/query aplica cinco camadas:

Só SELECT — qualquer INSERT/UPDATE/DELETE/MERGE/DDL responde 403.
Sem cruzar workspace — referência a dataset de outro cliente ou a outro projeto: 403.
Sem construções perigosas — EXTERNAL_QUERY, INFORMATION_SCHEMA, JOBS_* e afins: 403.
Só marts publicados — apenas *_gold e *_silver; apontar para bronze ou outro dataset: 403.
Guarda de custo — teto de bytes faturados (maximumBytesBilled) aplicado ao job.

Ou seja: não é a segurança de isolamento que está pendente — ela é fail-closed por desenho e testada. O que está pendente é a prova independente de que o teto de requisições se comporta corretamente quando o próprio limitador falha, e o gate de capacidade que liga a exposição externa. Permissão, aliás, também já está desenhada: /api/v1/tables exige a ação de exportação de dados (member+); /api/v1/query, SQL livre, exige admin+ e o escopo read/read_query na chave.

A alternativa que está disponível

Para consumo externo de dados hoje, o caminho é o feed OData v4 (Preview, Aula 3). Ele cobre a leitura das tabelas dos marts publicados, dobra filtro e projeção para o servidor, pagina de 1.000 em 1.000 e é consumido nativamente por Power BI, Excel, Tableau e qualquer cliente OData v4.

Superfície	Estado	Quando usar
Feed OData v4 (`/api/v1/odata`)	`Preview`	use isto — leitura externa dos marts publicados, com folding e paginação
`GET /api/v1/tables` (catálogo + linhas)	Fora de GA	não construa; o catálogo e as linhas saem pelo service document e pelas entidades OData
`POST /api/v1/query` (SQL livre)	Fora de GA	não construa; para SQL livre, use o produto por dentro (consulta e wizard), não a API
API de escrita	`Roadmap`	não existe — a plataforma é somente leitura por desenho

Exemplo: a Aurora Varejo redesenhando o ETL

O time de dados da Aurora Varejo queria um job noturno que fizesse POST /api/v1/query com SELECT data, SUM(total) FROM aurora_gold.vendas GROUP BY data e gravasse o resultado no data warehouse de um parceiro. Lendo esta aula, o time para e refaz a conta. A rota está fora de GA: o job poderia receber 503 como estado esperado em qualquer noite, e ninguém dentro da Aurora teria a quem recorrer, porque não existe SLA a invocar.

O redesenho é curto. O parceiro passa a consumir o feed OData da entidade vendas, filtrando por data ge <último carregado> — o filtro dobra para o servidor, lê só a janela nova e segue o @odata.nextLink até o fim. A agregação por dia, que era a razão do SQL livre, vira uma tabela gold agregada publicada pelo próprio pipeline da Aurora: o cálculo acontece onde deveria acontecer — dentro do datalake, uma vez — e o consumo externo fica barato e estável. A integração ficou mais simples do que a original, e não depende de nada retido.

Erros comuns

Erro	Por que machuca	O que fazer
"A doc existe, então posso usar"	a doc é contrato para planejamento; a rota não está liberada	use o feed OData (Aula 3)
Tratar `503` da rota REST como incidente a escalar	fora de GA, `503` é estado esperado	não escale; migre a integração para o OData
Pedir ao cliente para "testar em produção com cuidado"	é rota cobrável sem teto re-provado	não exponha o cliente; o custo é dele
Prometer SLA ou prazo de GA ao cliente	a liberação depende de evidência, não de calendário	diga o estado real: fora de GA, sem data
Levar SQL livre para fora porque "é mais flexível"	SQL livre externo é a rota mais sensível de todas	agregue no datalake e publique um mart gold
Expor a chave num cliente só para "testar a REST"	a chave lê todos os marts publicados	chave só no servidor (Aula 2)

Estado

API de consulta REST (/api/v1/query, /api/v1/tables) = fora de GA, indisponível para uso externo hoje; o claim de /api/v1 como disponível está barrado por evidência pendente (limitador fail-closed re-provado de forma independente + gate de capacidade da API). As defesas de isolamento, o modo somente-leitura, o cache de consulta idêntica (R$ 0) e a guarda de custo já existem e são testadas — não são elas que faltam. Alternativa disponível: feed OData v4 = Preview (sem SLA). API de escrita = Roadmap. Em toda superfície: somente leitura, escopo por workspace, PII nunca sai pela API, e valor em BRL é projeção.

Faça você mesmo#

Esta aula é de conhecimento: não há exercício operacional. Leia, assista e responda à checagem rápida. Não chame /api/v1/query nem /api/v1/tables — a rota está fora de GA e não deve receber tráfego seu; o curso não pede isso em nenhum momento.

Para fixar, faça o exercício de redação que o curso inteiro preparou: escolha uma integração real que você teria construído sobre a API REST, e escreva três parágrafos curtos — (1) o que ela precisava, (2) por que a rota REST não serve hoje, citando o motivo do bloqueio, e (3) como a mesma necessidade se resolve com o feed OData mais um mart gold agregado. Se não couber em três parágrafos, provavelmente a necessidade real era modelagem dentro do datalake, não API.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

Capacidades ensinadas#

(conceitual — sem capacidade específica da matriz) — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".