Repository navigation
Rotas da API Next
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
|
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).
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 deuser/,tables/estripe/. -
getTokenFromRequest(req)(lib/authCookie.js): tenta o headerAuthorization: Bearer, depois o cookietokene por últimoreq.body.token. Usado porrefreshToken,setSession,validateToken,updatePictureProfilee, viarequireChatbotAuth, 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.
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.
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.
| 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 |
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.
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 |
| 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 |
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 |
| 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 |
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.
| 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) |
Assinaturas, planos e cupons. Documentado em Stripe.
| 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.
| 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.
| 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 |
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 |
-
Rotas que respondem 200 em erro:
deleteAccount,deletePictureProfile,getAllUserseupdateProfilerespondem200com corpo vazio quando a chamada falha (ocatchnão retorna nada).updateUserresponde200com{ errors: [...] }.activeAccountresponde200 { 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),falsecom 500 (getAlreadySubscribed) e{ spatialCoverage: null }(getSpatialCoverage). -
Handlers que quebram no próprio erro: em
areas/*, a função devolvenullnocatche o handler acessaresult.errors, o que gera umTypeError.updateProfileSurveyfazresult.errors.lengthantes de testar"err". Emthemes/getDatasetsByThemes, ocatchfazreturn "err"sem responder, então a requisição fica pendurada até o timeout. -
Arquivos que não são handlers em
pages/api/: osgetAll*delicense,organizations,pipeline,statusetags, osindex.jse os módulos de cliente dedatasets/tablestambém viram URLs/api/.... Chamados por HTTP, não respondem. Os de edição (postDataset,deleteDataset,postTable,deleteTable,getDatasetEdit,getTableEdit,getAllTableInDataset) leem o token comjs-cookie, mas o cookietokenéhttpOnlye 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/getAllUserse a rota HTTP deresearchers/getInvitedResearchers.isKeyActivepode ser chamada de fora do website. Confirme antes de remover. -
Chamadas diretas do navegador ao backend:
getSearchDatasets,getMoreFacetSearchDatasetsegetBigTableQuerysão importados por componentes e rodam no cliente, sem passar pelas rotas Next. -
Senha na query string:
getToken,registerAccount,updatePasswordegetUserTestCypressrecebem 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,getAllPeopleegetTeamMembersautenticam no backend comBACKEND_AUTH_EMAIL/BACKEND_AUTH_PASSWORD, a cada chamada.getIdUsernão exige login e diz se um email tem conta ativa. -
permission_sudocom formato trocado:getPermissionSudodevolve{ permission: { hasSudo, email } }, mascheckBDSudo, empages/dataset/[dataset].js, lêisAdmineemailno primeiro nível. Por isso o cache nunca é aproveitado e a página chamagetUsertoda vez. -
downloadTable:desvêm do cliente. Quem decide se o arquivo BD Pro é liberado é ois_subscription_activedo 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.