Skip to content

Rotas da API Next

AldemirLucas edited this page Oct 26, 2026 · 1 revision

Rotas da API Next (pages/api/)

Mapa das rotas em next/pages/api/, agrupadas por pasta. Para o desenho geral (quem chama o quê), veja Arquitetura. Não há arquivos soltos na raiz de pages/api/: tudo fica em subpastas.

Nem todo arquivo em pages/api/ é uma rota HTTP de verdade. Há três tipos:

Tipo Como reconhecer Exemplo
Rota export default async function handler(req, res) tables/getTable.js
Módulo de servidor Exporta funções nomeadas, importadas em getStaticProps/getServerSideProps blog/index.js, docs/index.js, faqs/index.js
Módulo de cliente export default recebe argumentos comuns (não req, res). É importado direto por componentes, então roda no navegador e chama o backend sem passar pelo Next datasets/getSearchDatasets.js, tables/getBigTableQuery.js

Padrões transversais

URL do backend

Não existe um módulo central: cada arquivo declara a própria constante.

const API_URL = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/graphql`

Algumas rotas usam endpoints REST do backend, no mesmo NEXT_PUBLIC_API_URL: /search/, /facet_values/, /tables/stats/, /tables/<id>/columns/ e /account/account_activate_confirm/<uid>/<token>/. O chatbot usa process.env.CHATBOT_URL.

As queries são montadas por interpolação de string (allTable (id: "${id}")). Poucas usam variáveis GraphQL: registerAccount, updateUser, refreshToken e lib/requireChatbotAuth.js. O locale vira sufixo de campo com capitalize do lodash (name${capitalize(locale)} → namePt, nameEn, nameEs).

Token

O token é o JWT do backend, guardado no cookie httpOnly token (veja Autenticação). As rotas leem esse token de duas formas:

  • Direto do cookie: req.cookies.token. É o caso da maioria das rotas de user/, tables/ e stripe/.
  • getTokenFromRequest(req) (lib/authCookie.js): tenta o header Authorization: Bearer, depois o cookie token e por último req.body.token. Usado por refreshToken, setSession, validateToken, updatePictureProfile e, via requireChatbotAuth, pelas rotas do chatbot.

Várias rotas de user/ também aceitam o token em base64 no parâmetro q (if(req.query.q) return atob(req.query.q)), mas nenhum chamador do repositório usa isso.

O token segue para o backend como Authorization: Bearer <token>. A rota não valida o token antes: quem valida é o backend. As exceções são o chatbot, getUser, refreshToken, setSession e validateToken, que devolvem 401 (ou 400, no caso de setSession) quando não há token.

Parâmetros em base64

A convenção é mandar os parâmetros na query string codificados com btoa no cliente e decodificados com atob na rota. As letras não têm significado fixo: p costuma ser o id principal, q o segundo id, r o id do admin, s um status.

// cliente — components/organisms/TablePage.js
fetch(`/api/tables/getStatusTableUpdateNotification?p=${btoa(idUser)}&q=${btoa(id)}`)
// rota
const user = atob(req.query.p)
const tableId = atob(req.query.q)

registerAccount decodifica com Buffer.from(x, 'base64'), para aceitar UTF-8 no nome. Rotas mais novas usam parâmetros legíveis: getTable?id=&locale=, getTableColumns?id=, getSpatialCoverage?id=&locale=, getResearchPaper?id=.

Quase tudo é GET, inclusive as mutations (deleteAccount, updatePassword, registerAccount...). Só verificam o método: clearSession, refreshToken, validateToken (GET/POST), setSession, updatePictureProfile e getUserTestCypress (POST), além do chatbot.

Formato de erro

O padrão mais comum é:

if (result.errors) return res.status(500).json({ error: result.errors, success: false })
if (result === "err") return res.status(500).json({ error: "err", success: false })
return res.status(200).json({ resource: ..., success: true })

A função interna devolve a string "err" no catch, e o handler testa result.errors (erros do GraphQL) e "err" (falha de rede). Muitas rotas fogem do padrão: veja Pontos de atenção. cleanGraphQLResponse, de utils.js, achata edges/node antes de responder em getTable, getInformationRequest, getRawDataSource, getResearchPaper, isKeyActive e themes/getAllThemes.

Grupos

areas

Rota Parâmetros Backend Token Quem usa
getArea slug, locale query allArea(slug) não ninguém
getAreas locale query allArea não ninguém
getCountries locale query allArea(administrativeLevel: A_0) não ninguém

blog, caseStudies, docs, faqs (conteúdo local)

Módulos de servidor que leem markdown do disco com fs e gray-matter. Não fazem HTTP nem falam com o backend.

Módulo Lê de Funções Quem usa
blog/index.js blog/<locale>/*.md getAllPosts, getPostBySlug, getFilenameForSlug, getSlugForLocale, serializePost pages/blog/index.js, pages/blog/[slug].js
blog/categories.js — objeto categories pages/blog/[slug].js, components/organisms/blog/Home.js
caseStudies/index.js content/caseStudies/<locale>/ getAllCaseStudies, getCaseStudiesById, serializeCaseStudies pages/case-studies/index.js, pages/case-studies/[id].js
docs/index.js content/docs/<locale>/ getAllDocs, getDocsBySlug, serializeDoc pages/docs/[slug].js
faqs/index.js content/<dir>/<locale>/ (dir padrão FAQ) getAllFAQs pages/faq.js, bdpro.js, services.js, chatbot-lp.js

getAllPosts só lista posts com published: true, exceto quando NEXT_PUBLIC_BASE_URL_FRONTEND é http://localhost:3000 ou https://development.basedosdados.org.

chatbot

Proxy para ${CHATBOT_URL}/api/v1/chatbot/.... Todas usam requireChatbotAuth: 401 sem token válido e 403 sem has_chatbot_access. Os erros do serviço são repassados com o status original. Detalhes do fluxo em Chatbot.

Rota Métodos Destino Quem usa
threads GET, POST, DELETE (?id=) /threads, /threads/<id> hooks/useThreads.js, hooks/useChatbot.js
messages GET, POST (?threadId=) /threads/<id>/messages. O POST faz streaming em application/x-ndjson hooks/useChatbot.js
feedback PUT (?messageId=) /messages/<id>/feedback hooks/useChatbot.js
exports POST (?messageId=&queryRef=&format=) /messages/<id>/exports (formato padrão CSV) hooks/useChatbot.js

datasets

Arquivo Tipo Parâmetros Backend Token Quem usa
getDataset servidor id (UUID), locale query allDataset(id) não getStaticProps de pages/dataset/[dataset].js
getListDatasets servidor + rota — query allDataset, sem under_review/excluded não getStaticPaths de pages/dataset/[dataset].js
getUserGuide servidor slug, locale lê content/userGuide/<locale>/<slug>.md — pages/dataset/[dataset].js
getSpatialCoverage rota id (UUID), locale query allDataset(id) { spatialCoverageName<Locale> } não pages/dataset/[dataset].js
getSearchDatasets cliente filter, page, locale REST GET /search/ não pages/search.js
getMoreFacetSearchDatasets cliente facet, params, locale REST GET /facet_values/ não components/atoms/FilterAccordion.js
getDatasetEdit, postDataset, deleteDataset cliente — allDataset, CreateUpdateDataset, DeleteDataset via js-cookie ninguém

informationRequests, rawDataSources, researchPapers

Rotas de leitura, sem token, usadas pelas páginas de detalhe dentro do dataset.

Rota Parâmetros Backend Quem usa
informationRequests/getInformationRequest id, locale query allInformationrequest(id) components/organisms/InformationRequestPage.js
rawDataSources/getRawDataSource id, locale query allRawdatasource(id) components/organisms/RawDataSourcesPage.js
researchPapers/getResearchPaper id query allResearchpaper(id). Devolve 404 se não achar components/organisms/ResearchPaperPage.js

keys

Rota Parâmetros Backend Token Quem usa
isKeyActive id (a chave em texto) Calcula o SHA-256 da chave e chama query allDataapikey(hash). Devolve isActive, createdAt e expiresAt, ou 404 não ninguém no repositório

license, organizations, pipeline, status, tags

Cada pasta tem um getAll*.js (allLicense, allOrganization, allPipeline, allStatus, allTag) e um index.js que o reexporta. Nenhum é handler e nenhum é importado fora de pages/api/. São restos de um formulário de edição de datasets que não existe mais.

researchers

Arquivo Tipo Parâmetros Backend Quem usa
getInvitedResearchers servidor + rota locale query allResearcher. Separa em current e alumni getServerSideProps de pages/invited-researchers.js (importa a função; a rota HTTP não tem chamador)

stripe

Assinaturas, planos e cupons. Documentado em Stripe.

tables

Arquivo Tipo Parâmetros Backend Token Quem usa
getTable rota id (UUID), locale query allTable(id) não components/organisms/TablePage.js
getTableColumns rota id (UUID) REST /tables/<id>/columns/ + query allColumn(table_Id) para as descrições traduzidas não components/molecules/TableColumns.js
getDictionaryTable rota p = id do dataset query allDataset { tables(slug: "dicionario") }. Se não achar, tenta "dictionary" não components/molecules/TableColumns.js
getTablesStats rota — REST GET /tables/stats/ não components/organisms/home/TablesStats.js
downloadTable rota p = dataset GCP, q = tabela GCP, d = download permitido, s = aviso ("free") mutation verifyToken + stream do arquivo do GCS (veja abaixo) opcional components/molecules/DataInformationQuery.js, TableColumns.js
getStatusTableUpdateNotification rota p = usuário, q = tabela query statusTableUpdateNotification sim TablePage.js
toggleTableUpdateNotification rota p, q, s = status atual mutation TableUpadateNotification ou DeactivateTableUpadateNotification sim TablePage.js
disableAllTableUpdateNotifications rota p = usuário mutation DeactivateAllTableUpadateNotification sim componentsUserPage/Account.js
getBigTableQuery cliente id, columns, includeTranslation query getTableOneBigTableQuery não components/molecules/DataInformationQuery.js
getTableEdit, postTable, deleteTable, getAllTableInDataset cliente — allTable, CreateUpdateTable, DeleteTable via js-cookie ninguém

Download (downloadTable): se d decodificado for "false", a rota responde 500. Com token cujo payload tem is_subscription_active: true, baixa ${URL_DOWNLOAD_CLOSED}<dataset>/<tabela>/<tabela>_bdpro.csv.gz. Senão, com s === "free", baixa ${URL_DOWNLOAD_OPEN}<dataset>/<tabela>/<tabela>.csv.gz. Se o primeiro download falhar, a rota tenta o arquivo aberto. O arquivo vem de https://storage.googleapis.com/ e é repassado em stream com Content-Type: application/gzip.

team

Rota Parâmetros Backend Token Quem usa
getAllTeams locale query allTeam não pages/about-us.js
getAllPeople locale query allAccount(profile: A_1) conta de serviço pages/about-us.js
getTeamMembers team (slug), locale query allAccount(careers_Team_Slug, profile: A_1) conta de serviço pages/about-us.js

"Conta de serviço": a rota faz mutation authToken com BACKEND_AUTH_EMAIL/BACKEND_AUTH_PASSWORD a cada chamada e usa esse token, não o do usuário.

themes

Rota Parâmetros Backend Quem usa
getDatasetsByThemes themes (array ou "[a,b]"), locale REST GET /search/?theme=... (timeout de 5 s). Devolve results sem envelope components/molecules/ThemeCatalog.js
getAllThemes locale query allTheme ninguém
getAllDatasets locale REST GET /search/ ninguém

user

Sessão e conta

Rota Parâmetros Backend Token Quem usa
getToken (login) a = email, q = senha, s = não gravar cookie mutation authToken. Grava o cookie token e devolve o user não pages/user/login.js, componentsUserPage/NewPassword.js
setSession (POST) token no header ou no body — (só grava o cookie) sim pages/user/login.js
clearSession (GET/POST) — — (apaga o cookie) não clearClientSession em utils.js
refreshToken (GET/POST) — mutation refreshToken e regrava o cookie sim pages/user/index.js, hooks/useChatbotAuth.js
validateToken (GET/POST) — mutation verifyToken. Devolve has_chatbot_access sim pages/user/index.js, pages/chatbot-lp.js, ChatbotAccessGate.js, useChatbotAuth.js
registerAccount f, l, e, p, c (telefone, opcional) mutation CreateUpdateAccount não pages/user/register.js
activeAccount q = uid, p = token de ativação (sem base64) REST POST /account/account_activate_confirm/<q>/<p>/ não getServerSideProps de pages/user/activate-account.js
getIdUser p = email query allAccount(email). Devolve id e isActive conta de serviço login.js, check-email.js, password-recovery.js, componentsUserPage/Accesses.js
getUser p = id da conta query allAccount(id). Ordena internalSubscription com BD Pro primeiro sim (401 sem cookie) página do usuário, login.js, survey.js, dataset/[dataset].js, ImgCrop.js
updateProfile p, f, l, e, w, g, t, li mutation CreateUpdateAccount sim componentsUserPage/ProfileConfiguration.js
updateProfileSurvey p, f, l, i, t, g, d, e, s (pular) mutation CreateUpdateAccount sim pages/user/survey.js
updateUser p = id numérico, q = telefone mutation CreateUpdateAccount(phone) sim componentsUserPage/Account.js
updatePassword b = id, p = nova senha mutation CreateUpdateAccount(password) sim componentsUserPage/NewPassword.js
updatePictureProfile (POST) body JSON: id, fileBase64, fileName, contentType upload multipart para CreateUpdateAccount(picture) sim components/molecules/ImgCrop.js
deletePictureProfile p = id mutation DeleteAccountPictureMutation sim ProfileConfiguration.js
deleteAccount p = id mutation DeleteAccount sim componentsUserPage/Account.js
changeUserGcpEmail p = email mutation changeUserGcpEmail sim componentsUserPage/BigQuery.js, PlansAndPayment.js

Assinatura e membros

Rota Parâmetros Backend Token Quem usa
getAlreadySubscribed p = id, type (bd_pro, chatbot ou vazio) query allAccount { subscriptionSet, internalSubscription }. Devolve true/false sim pages/prices.js, pages/chatbot-lp.js, PlansAndPayment.js
getMembers p = id do admin query allAccount. Filtra a assinatura BD Pro/empresas sim componentsUserPage/Accesses.js, Account.js
addMemberInSubscription r = admin, p = id do membro allAccount (acha a assinatura) + mutation addStripeSubscriptionMember sim Accesses.js
addMemberInSubscriptionServiceAccount r = admin, p = email mutation addStripeSubscriptionServiceAccount sim Accesses.js
removeMemberInSubscription r = admin, p = id do membro mutation removeStripeSubscriptionMember sim Accesses.js
removeAllMembersInSubscription p = admin mutation removeAllStripeSubscriptionMembers sim Accesses.js

A assinatura BD Pro é identificada pelo slug em stripeSubscription: contém bd_pro ou empresas.

Outras

Rota Parâmetros O que faz Quem usa
setPermissionSudo p = é admin, q = email Grava o cookie httpOnly permission_sudo com {hasSudo, email} pages/dataset/[dataset].js
getPermissionSudo — Lê o cookie e devolve { permission } pages/dataset/[dataset].js
isEmailInGoogleGroup p = email query isEmailInGoogleGroup ninguém
getAllUsers — query allAccount (todas as contas) com o token do cookie ninguém
getUserTestCypress (POST) a = email, p = senha authToken + allAccount(id). Devolve token e usuário cypress/support/commands.js

Pontos de atenção

  • Rotas que respondem 200 em erro: deleteAccount, deletePictureProfile, getAllUsers e updateProfile respondem 200 com corpo vazio quando a chamada falha (o catch não retorna nada). updateUser responde 200 com { errors: [...] }. activeAccount responde 200 { success: true } sempre, e a linha seguinte (res.status(500)) nunca tem efeito.
  • Formatos de erro diferentes: além de { error, success: false }, há { errors } (getAllPeople, updateProfileSurvey), [] com 500 (getTeamMembers), false com 500 (getAlreadySubscribed) e { spatialCoverage: null } (getSpatialCoverage).
  • Handlers que quebram no próprio erro: em areas/*, a função devolve null no catch e o handler acessa result.errors, o que gera um TypeError. updateProfileSurvey faz result.errors.length antes de testar "err". Em themes/getDatasetsByThemes, o catch faz return "err" sem responder, então a requisição fica pendurada até o timeout.
  • Arquivos que não são handlers em pages/api/: os getAll* de license, organizations, pipeline, status e tags, os index.js e os módulos de cliente de datasets/tables também viram URLs /api/.... Chamados por HTTP, não respondem. Os de edição (postDataset, deleteDataset, postTable, deleteTable, getDatasetEdit, getTableEdit, getAllTableInDataset) leem o token com js-cookie, mas o cookie token é httpOnly e não é legível no JS. Nenhum deles tem chamador.
  • Rotas sem chamador no repositório: areas/*, themes/getAllThemes, themes/getAllDatasets, keys/isKeyActive, user/isEmailInGoogleGroup, user/getAllUsers e a rota HTTP de researchers/getInvitedResearchers. isKeyActive pode ser chamada de fora do website. Confirme antes de remover.
  • Chamadas diretas do navegador ao backend: getSearchDatasets, getMoreFacetSearchDatasets e getBigTableQuery são importados por componentes e rodam no cliente, sem passar pelas rotas Next.
  • Senha na query string: getToken, registerAccount, updatePassword e getUserTestCypress recebem a senha em base64 na URL. Base64 não é criptografia, e a URL pode aparecer em logs.
  • Conta de serviço em rota pública: getIdUser, getAllPeople e getTeamMembers autenticam no backend com BACKEND_AUTH_EMAIL/BACKEND_AUTH_PASSWORD, a cada chamada. getIdUser não exige login e diz se um email tem conta ativa.
  • permission_sudo com formato trocado: getPermissionSudo devolve { permission: { hasSudo, email } }, mas checkBDSudo, em pages/dataset/[dataset].js, lê isAdmin e email no primeiro nível. Por isso o cache nunca é aproveitado e a página chama getUser toda vez.
  • downloadTable: d e s vêm do cliente. Quem decide se o arquivo BD Pro é liberado é o is_subscription_active do token. Quando o arquivo pedido falha, a rota cai silenciosamente para o arquivo aberto.
  • getTablesStats é chamada com caminho relativo (fetch("api/tables/getTablesStats"), sem / inicial). Só funciona porque o componente roda na home.

Clone this wiki locally