Como um backup do Notion realmente funciona
Um backup é uma longa série de requisições a uma API que nunca foi projetada para backups. Você só tem uma cópia confiável quando sabe exatamente o que essa API devolve e o que não devolve.
Tudo começa com um token
O Notion usa integrações para decidir quem pode ler o quê. Você cria uma integração interna, e ela só consegue ler as páginas e os bancos de dados que você compartilha com ela. Não lê mais nada no workspace, e não lê nada até você compartilhar algo. O token identifica essa integração.
Esse é todo o modelo de acesso que o NotionManager usa. Não há senha do Notion, nem uma chave do workspace inteiro capaz de ler tudo, nem acesso a páginas que você não compartilhou. A lista de compartilhamento decide o que a integração pode ler, e o Notion aplica a mesma regra a qualquer outra ferramenta. Se você revogar a integração no Notion, toda execução seguinte falha na hora.
Depois é a API que decide o que é possível
A API do Notion é uma interface de leitura paginada para block e páginas. Devolve resultados em páginas de no máximo cem itens e limita quantas requisições você pode enviar por segundo. O que ela consegue representar, devolve por inteiro. O que não consegue, informa sem o conteúdo, em vez de adivinhar.
Paginação, limites de requisição e conteúdo ausente moldam o projeto de qualquer backup do Notion. Por isso um backup não é uma requisição só: é uma travessia com ritmo. Num workspace grande, pode levar minutos, dez minutos ou até mais. O NotionManager mostra o progresso ao vivo, então você sabe onde a cópia chegou.
O Notion também atualiza a API para corrigir falhas, adicionar recursos e melhorar a forma como organiza os dados. O NotionManager é construído sobre a versão mais recente da API, então o backup captura o máximo de informação que consegue.
O modelo de dados que um backup copia
Tudo no Notion é feito de block. Um parágrafo, um título, uma tarefa, um toggle e uma linha de tabela são block. Uma página é um block que contém outros block, então tudo o que você lê no Notion é uma árvore de block. Um backup lê essa árvore do mesmo jeito: começa num nó, lê os filhos e repete.
Um banco de dados é um contêiner de páginas. O conteúdo dele fica em uma ou mais fontes de dados, e cada linha de uma fonte de dados é uma página cujas propriedades essa fonte define. Uma view não guarda dados próprios. Ela define como você olha os dados: qual fonte de dados, quais filtros e ordenação, e se aparece como tabela, quadro, calendário ou galeria. A API do Notion devolve a estrutura essencial de uma view, e nenhum estilo.
Como o NotionManager lê um workspace
Uma travessia de cima para baixo, que continua até a API não devolver mais resultados.
- 1
Comece pelo que você compartilhou
O integration token expõe as páginas e os bancos de dados de nível superior que você compartilhou com ele. Essas são as raízes da travessia.
- 2
Leia cada um por inteiro
O NotionManager busca cada raiz com suas propriedades e seus block, página por página até a paginação acabar, para não deixar nada de fora.
- 3
Desça pelas páginas filhas
Ele busca cada página filha encontrada no caminho, uma após a outra e de forma recursiva, até não restar nenhuma.
- 4
Reconstrua a estrutura e leia de novo
O NotionManager transforma o que leu em páginas, bancos de dados e relações. O resultado é uma cópia somente leitura que você navega offline, com uma sensação próxima à do próprio Notion, e não um monte de JSON.
O que a API não faz, e o que acontece no lugar
| Limite da API do Notion | O que o NotionManager faz |
|---|---|
| A API limita requisições, então o backup demora mais | O NotionManager dá ritmo às requisições e espera quando bate num limite, então a cópia continua completa |
| Alguns tipos de block a API informa sem o conteúdo | A cópia guarda todo dado bruto que consegue ler, e a renderização marca o que falta, então a lacuna fica visível em vez de silenciosa |
| Estilo complexo de view: cores, layout, agrupamento, o quadro ou a galeria que você realmente olha | O NotionManager copia os dados por trás da view e reconstrói a view a partir das propriedades, imitando o Notion o mais perto que consegue |
| Sem feed de mudanças: a API não consegue dizer "estas três páginas mudaram desde terça" | Backup incremental e diferencial ainda não está disponível, então cada execução percorre todas as páginas e todos os block. Um block que não mudou não ocupa espaço extra em disco, e o NotionManager mantém os arquivos de mídia externos sem duplicatas, então o uso de disco fica sob controle |
| Sem escrita de volta: a API não restaura um workspace para você | A restauração de backup não é suportada diretamente. Toda ferramenta de backup que promete restaurar reconstrói o workspace por completo e carrega limites sérios: novos IDs, relações perdidas. O NotionManager não oferece restauração, por decisão de projeto |
| Tudo o que não foi compartilhado com a integração | Nada. A cópia contém exatamente as páginas que você compartilhou. O NotionManager pode restringir ainda mais, a um subconjunto dessas páginas, e não consegue ir além disso |
Faça backup com o NotionManager
Crie uma integração, compartilhe com ela uma página ou um banco de dados e veja a primeira cópia aparecer.
Para onde ir agora
Perguntas frequentes
O NotionManager precisa da minha senha do Notion?
Não. Ele usa um integration token, e essa integração só consegue ler o que você compartilhou com ela explicitamente. Nenhuma credencial do workspace inteiro entra no processo.
Por que um backup leva minutos, ou mais?
Primeiro, a API do Notion limita chamadas com rigor, e qualquer tentativa de acelerar um backup acaba em chamadas simultâneas que são bloqueadas. Segundo, todo backup é uma leitura completa: pode ser que os dados não precisem ser baixados de novo, mas o NotionManager precisa percorrer todas as páginas e todos os block para garantir que a cópia está inteira.
Dá para fazer backup só do que mudou?
A API do Notion não oferece uma lista confiável de tudo o que mudou desde o último backup. Então cada execução é um backup completo, e o NotionManager garante que dados repetidos sejam guardados uma única vez.
O que acontece com block que a API não descreve?
O NotionManager registra o tipo declarado do block e a posição dele na árvore, então a lacuna aparece na cópia navegável, em vez de ser um buraco silencioso no meio da página.