Importador de migração do TinyURL: como funciona e falhas

O importador de migração do TinyURL recebe um token de API, um domínio de destino do Elido e uma estratégia de conflito, e então copia os seus links do TinyURL para o Elido como um único job em segundo plano. Ele tem um defeito conhecido e sério: chama GET /aliases em api.tinyurl.com, e esse caminho não existe na API publicada do TinyURL. Este post cobre o que o importador faz, o que verificamos e o que não verificamos.

Se você quer o passo a passo para planejar a saída do TinyURL (o que pode ser redirecionado, mapeamento de CSV, checklist de transição), leia Migrar do TinyURL. Este é o lado da engenharia.

O bug conhecido

A busca de página do importador monta esta requisição:

GET https://api.tinyurl.com/aliases?page=1&per_page=100
Authorization: Bearer <token>

e espera receber de volta {"data": [{alias, url, title, tags}], "meta": {"total", "has_more"}}.

A especificação OpenAPI do TinyURL (acessada em 2026-10-02) não define nenhum caminho /aliases. A listagem é GET /urls/{type}, em que type é available ou archived, com filtros opcionais from, to e search (com prefixo alias: ou tag:). A especificação não define parâmetros page ou per_page nem limites de taxa. As operações de alias ficam em /alias/{domain}/{alias}.

Ou seja, o contrato de paginação do nosso código nunca veio do TinyURL. O nosso teste unitário serve uma resposta escrita à mão nesse formato e passa, o que prova que o parser corresponde à nossa suposição e nada sobre o TinyURL. Não executamos o importador contra uma conta real do TinyURL, porque isso exige um token de plano pago. Até que o façamos, não planeje uma migração em torno dele. A correção está registrada no nosso backlog interno: migrar para /urls/available (e /urls/archived atrás de uma flag), percorrer janelas from/to, fazer o parse de forma defensiva e testar com uma resposta real capturada. Se a resposta real traz uma lista ou um único objeto é algo que a especificação deixa pouco claro.

O que o worker faz depois de receber uma página

A página de integrações em um workspace DEMO com dados sintéticos. A migração do TinyURL é iniciada a partir daqui.

Tudo o que vem depois da chamada HTTP é independente da questão do endpoint. Esta parte podemos afirmar a partir do código.

• Início. POST com token, target_domain_id e conflict_strategy opcional. O handler rejeita um token vazio, um domínio ausente e qualquer estratégia fora de suffix, skip, fail, depois responde 202 com o job e executa o worker em uma goroutine em segundo plano, desacoplada da requisição.
• Por link. Uma linha sem URL ou sem alias conta como falha, com um motivo. Caso contrário, o alias vira o slug, o destino e o título são copiados (título truncado em 200 caracteres) e as tags são copiadas com imported:tinyurl acrescentada.
• Progresso. Os contadores são gravados na linha do job a cada 50 links. No máximo 1.000 linhas de erro são registradas por job.
• Erros de autenticação e de taxa. Um 401 ou 403 faz o job falhar com a mensagem "check the bearer token", e um 429 o faz falhar como limitado por taxa. Não há nova tentativa nem backoff: o job para.

Regras de conflito

A lista de links em um workspace DEMO. Os links importados levam a tag imported:tinyurl, então você pode filtrar um lote para revisão.

Antes de cada inserção, o worker faz uma consulta indexada por (domain, slug).

• suffix (padrão) tenta alias-2, alias-3, até alias-50, e faz a linha falhar se todos estiverem ocupados.
• skip deixa o link existente do Elido em paz e registra a linha de origem no log.
• fail faz o job falhar no primeiro conflito.

O TinyURL chama isso de aliases, o Elido chama de slugs. É a mesma coisa: os caracteres depois do host. Se o seu domínio de destino estiver vazio, os aliases passam sem alteração.

Limites

Um único conjunto de constantes, usado por todos os fornecedores de migração: 50.000 links por execução, um orçamento de 30 minutos, progresso a cada 50 links, 1.000 erros registrados.

Dois comportamentos merecem atenção. Quando o limite de 50.000 é atingido, o laço simplesmente para e o job é concluído; ele não falha e não manda você contatar ninguém. Compare as contagens finais com o total da sua origem. Quando o orçamento de 30 minutos se esgota, o job é marcado como falho com o número importado até então.

O worker vive dentro do api-core. Um deploy ou uma falha no meio da execução o mata, e uma varredura que roda a cada cinco minutos muda para failed os jobs sem progresso há 30 minutos. Não há cursor salvo, então você reinicia o job. Executar de novo é seguro com suffix ou skip, embora com suffix ele crie cópias -2 dos links que a primeira execução já gravou, então prefira skip em uma nova execução.

Tratamento do token

O token vai do corpo da requisição para a goroutine e para lugar nenhum mais. A linha do job não registra nenhum token, e nada é criptografado em repouso porque nada é armazenado. O corpo da requisição é lido com um limite de 4 KB.

O que o código não faz: não valida o token antes de começar e não verifica o plano. Um token inválido aparece como um job falho após a primeira requisição, não como um erro de formulário. Versões anteriores deste post descreviam uma etapa de verificação prévia em um endpoint de domínios. Essa etapa não existe no código, e a especificação do TinyURL também não tem esse caminho.

O que não é migrado

• Histórico de cliques. O importador lê apenas campos de links. Os novos cliques contam a partir do momento em que um link está ativo no Elido.
• Estilo de QR, templates, configurações de domínio de marca. Não são lidos. Um hostname de marca é uma etapa separada: adicione-o como domínio do Elido e mude o DNS, como explicado em domínios personalizados para links curtos.
• Links sem conta. Nenhum token consegue listá-los.

O importador não cria o domínio para você, não trata um campo domain do TinyURL e não tem upload de CSV próprio. Para migrações baseadas em arquivo, use o formulário de importação em massa ou o passo a passo em importação em massa a partir do Google Sheets.

Testando e contornando

Seguem duas seções práticas. Testar o importador. Migrar sem ele.

Uma forma segura de verificar uma importação

Quando o endpoint for corrigido, ou se você testar o importador por conta própria antes disso, comece pequeno. Crie um workspace descartável, adicione um domínio vazio e execute o job primeiro com a estratégia fail. Um domínio vazio significa nenhum conflito, então qualquer falha é um problema de parse ou de autenticação, não de colisão. Depois compare três números: a contagem de origem no TinyURL, o total que o job informa e os contadores de importados mais ignorados mais falhos. Como o worker toma meta.total da resposta que espera, uma divergência entre total e a sua contagem real é o primeiro sinal de que o formato da resposta difere do que o parser presume.

Depois filtre a lista de links por imported:tinyurl e abra dez links ao acaso. Confira o destino, o slug e o título em relação ao TinyURL. Em seguida, mude para skip em qualquer nova execução.

Como exportar do TinyURL sem o importador

A chamada de listagem documentada é GET /urls/available com um bearer token, e GET /urls/archived para links arquivados. Restrinja o resultado com datas from e to se a conta for grande, já que a especificação não traz parâmetros de página. Grave a saída em um arquivo antes de fazer qualquer outra coisa, reduza-a a destination, slug, title e carregue-a com o formulário em massa. Os detalhes desse mapeamento estão no guia prático. Também não verificamos o formato da resposta real, então inspecione uma resposta à mão antes de escrever scripts em cima dela.

O que vem a seguir

A sequência é: corrigir o endpoint, adicionar uma resposta real capturada como fixture de teste e depois reverificar cada número no guia prático e na página de destino da migração. A paginação e o limite real por requisição precisam ser medidos de novo em uma conta real, já que a especificação não traz nenhum dos dois. Se você precisa sair do TinyURL antes disso, compare as opções em Elido vs TinyURL e alternativas ao TinyURL, e use o caminho do CSV.

Relacionados no blog

• Migrar do TinyURL: o que muda, o que fica, o que quebra
• Entregando a migração do Bitly
• Entregando a migração do Rebrandly
• Entregando a migração do Short.io
• Links curtos como Terraform