[Pitch] EasyDown: uma API para posts públicos e os cuidados com mídias temporárias

Sou Zhang Bo, desenvolvedor do EasyDown. O projeto tem um downloader para navegador e uma API paga para integrar posts públicos de vídeo e imagem a outros produtos. Aqui quero compartilhar um problema de integração: o link original do post e a URL retornada para uma mídia têm papéis diferentes.

Um caso concreto é um aplicativo que recebe um link público do TikTok ou Instagram para montar uma lista de materiais que o usuário tem autorização para usar. Não basta chamar um endpoint e guardar o primeiro endereço de vídeo encontrado. Autenticação, validade dos links e novas tentativas precisam de um contrato claro no lado do cliente.

1. Guarde a origem; trate a mídia como temporária

No seu banco, separe pelo menos:

• a URL original enviada pelo usuário;
• o identificador interno da solicitação;
• a data da resolução;
• o estado de processamento;
• as referências de mídia obtidas naquela resolução.

Uma URL de CDN pode expirar ou deixar de funcionar. Guardá-la como identificador definitivo do conteúdo cria uma dependência frágil. A URL original permite identificar o que o usuário pediu, mas também não garante que o post continuará público ou disponível.

Essa separação é uma proposta de integração para o seu aplicativo, não uma promessa de disponibilidade permanente do serviço ou das plataformas.

2. Mantenha a credencial no backend

O navegador deve enviar o link do post ao seu backend. É o backend que faz a chamada autenticada e decide quais campos devolver ao usuário.

Navegador -> seu backend -> API de resolução <- resultado ou erroNavegador <- dados necessários para a interface

Um exemplo esquemático de entrada, enviado por HTTPS, é:

POST /api/v1/parseHost: api.easydown.orgAuthorization: Bearer <SEU_TOKEN>Content-Type: application/json{"url":"<URL_PUBLICA_DO_POST>"}

Os dois valores entre <...> são placeholders, não credenciais nem um post de teste. A chamada acima ilustra o contrato; ela não foi executada neste artigo.

Não coloque o Bearer token no JavaScript público. Evite registrá-lo em logs ou capturas de tela e não o inclua na URL da requisição. O acesso à API exige conta, token e créditos disponíveis.

Também não transforme seu backend em um proxy que baixa qualquer URL enviada por terceiros. Se você oferecer o download do arquivo, trate essa etapa separadamente: valide destinos e redirecionamentos, defina limites de tamanho e tempo e processe o conteúdo como não confiável.

3. Um timeout não significa que a operação não ocorreu

No cliente, um estado simples pode ser:

recebido -> resolvendo -> resolvido -> erro conhecido -> resultado desconhecido

O último caso importa. Se a conexão cair, o cliente pode não saber se o servidor já processou a solicitação. Reenviar automaticamente toda falha pode repetir operações e aumentar o consumo de créditos.

Para a mesma origem, considere consolidar solicitações simultâneas no seu aplicativo. Use uma política limitada de novas tentativas e diferencie erro de autenticação, entrada incompatível, limite temporário e falha de rede. Não presuma que enviar um cabeçalho de idempotência inventado fará o provedor deduplicar chamadas: isso precisa estar documentado e ser suportado.

No EasyDown, o custo depende da plataforma e do resultado do processamento. Por isso, não recomendo escrever uma regra geral de que qualquer tentativa que terminou em erro será gratuita.

4. Não descarte a estrutura do post

A escolha do endpoint muda o que você precisa mapear:

Endpoint

Uso no cliente

POST /api/v1/parse

Um modelo normalizado de mídia para as plataformas suportadas.

POST /api/v1/platforms/{platform}/parse

Mídia normalizada e o objeto final sanitizado da plataforma solicitada.

Na resposta unificada, a mídia fica em data, com coleções como images, videos e audios. Não presuma que uma resposta de endpoint específico tenha exatamente o mesmo envelope da unificada: confira o esquema antes de reutilizar o mapeamento.

Um post pode conter vídeo, imagens ou várias mídias. Preserve a estrutura recebida antes de escolher uma representação para sua interface. Não transforme automaticamente toda resposta em um único campo videoUrl, nem prometa que todo post terá as mesmas opções de qualidade ou áudio.

O escopo também precisa ficar claro para o usuário: URLs de posts públicos suportados. Não prometa acesso a conteúdo privado, importação de perfis inteiros ou transmissões ao vivo. Conteúdo público não equivale a autorização para republicá-lo.

A referência da API do EasyDown reúne os endpoints e o suporte por plataforma. O serviço é pago por créditos; o downloader gratuito do navegador é outro fluxo.

Essas separações deixam explícito o que pertence à origem, ao resultado temporário e à lógica do seu produto. Elas também ajudam a explicar falhas sem exibir um falso “download concluído”.

Nota de transparência: texto em português preparado com auxílio de IA. Os fluxos acima são exemplos de arquitetura do cliente, sem benchmark de produção ou execução de chamadas pagas neste artigo.

Source