Analise e valide expressões cron via API REST

Você está construindo um painel de administração onde os usuários agendam trabalhos recorrentes. Eles digitam uma expressão cron em um campo de texto, clique em salvar e espere que o sistema faça a coisa certa. O problema: sintaxe cron é enigmático. */15 * * * * é bastante claro, mas e quanto 0 9 1-15 * 1-5? A maioria dos usuários (e muitos desenvolvedores) não consegue ler isso de relance.

Você precisa mostrar aos usuários o que sua expressão significa *antes* de salvá-la. Uma descrição como "Às 09h00 dos dias 1 a 15, de segunda a sexta-feira" vale mais do que uma dica de ferramenta vinculando para crontab.guru.

A API do analisador cron do Botoi faz três coisas em uma única solicitação POST: valida a expressão, gera uma descrição legível e retorna os próximos tempos de execução agendados. Sem cron bibliotecas para instalar, nenhuma lógica de análise para manter.

O ponto final da análise

Envie uma expressão cron para /v1/cron/parse e receba de volta um detalhamento estruturado.

curl -X POST https://api.botoi.com/v1/cron/parse \\
  -H "Content-Type: application/json" \\
  -d '{"expression": "*/15 * * * *"}'

Resposta:

{
  "success": true,
  "data": {
    "isValid": true,
    "description": "Every 15 minutes",
    "nextRuns": [
      "2026-03-26T18:30:00Z",
      "2026-03-26T18:45:00Z",
      "2026-03-26T19:00:00Z",
      "2026-03-26T19:15:00Z",
      "2026-03-26T19:30:00Z"
    ],
    "parts": {
      "minute": "*/15",
      "hour": "*",
      "dayOfMonth": "*",
      "month": "*",
      "dayOfWeek": "*"
    }
  }
}

A resposta inclui tudo que você precisa: um isValid bandeira, um inglês simples description, os próximos cinco tempos de execução em UTC e o indivíduo parts dividido por campo. Você pode exibir a descrição diretamente na sua UI e usar o nextRuns array para mostrar uma prévia das próximas execuções.

Obtenha mais corridas futuras

Se você precisar de mais de cinco datas de visualização, ou se você se preocupa apenas com a programação e não com o descrição, use o /v1/cron/next ponto final. Passe um count parâmetro para controlar quantos tempos de execução futuros você receberá.

curl -X POST https://api.botoi.com/v1/cron/next \\
  -H "Content-Type: application/json" \\
  -d '{"expression": "0 9 * * MON-FRI", "count": 5}'

Resposta:

{
  "success": true,
  "data": {
    "nextRuns": [
      "2026-03-27T09:00:00Z",
      "2026-03-30T09:00:00Z",
      "2026-03-31T09:00:00Z",
      "2026-04-01T09:00:00Z",
      "2026-04-02T09:00:00Z"
    ]
  }
}

Observe a diferença entre 27 de março (sexta-feira) e 30 de março (segunda-feira). A expressão 0 9 * * MON-FRI pula fins de semana e a API reflete isso corretamente.

Crie um widget de visualização do cron

Veja como conectar o endpoint de análise a um campo de entrada de frontend. Conforme o usuário digita um cron expressão, o widget chama a API e mostra a descrição e as próximas execuções em tempo real.

async function parseCron(expression) {
  const res = await fetch("https://api.botoi.com/v1/cron/parse", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ expression }),
  });
  return res.json();
}

// Example: user types "0 9 * * MON-FRI" into a text input
const input = document.querySelector("#cron-input");
const preview = document.querySelector("#cron-preview");

input.addEventListener("input", async (e) => {
  const { data } = await parseCron(e.target.value);

  if (data.isValid) {
    preview.innerHTML = \`
      <p class="text-green-600">\\\${data.description}</p>
      <ul>
        \\\${data.nextRuns
          .map((run) => \`<li>\\\${new Date(run).toLocaleString()}</li>\`)
          .join("")}
      </ul>
    \

Para uso em produção, adicione um debounce (200-300ms) para não disparar uma solicitação a cada pressionamento de tecla. A API responde em menos de 50 ms a partir da borda da Cloudflare, então a visualização parece instantânea assim que o pedido sai.

Versão React / Pré-agir

Se você estiver usando React ou Preact, aqui está um componente que envolve a mesma lógica com um AbortController para cancelar solicitações obsoletas.

import { useState, useEffect } from "react";

function CronPreview({ value }) {
  const [result, setResult] = useState(null);

  useEffect(() => {
    if (!value.trim()) {
      setResult(null);
      return;
    }

    const controller = new AbortController();
    fetch("https://api.botoi.com/v1/cron/parse", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ expression: value }),
      signal: controller.signal,
    })
      .then((r) => r.json())
      .then(({ data }) => setResult(data))
      .catch(() => {});

    return () => controller.abort();
  }, [value]);

  if (!result) return null;

  if (!result.isValid) {
    return <p className="text-red-600">Invalid expression</p>;
  }

  return (
    <div>
      <p className="font-medium">{result.description}</p>
      <p className="text-sm text-gray-500 mt-1">
        Next run: {new Date(result.nextRuns[0]).toLocaleString()}
      </p>
    </div>
  );
}

Valide a entrada do usuário antes de salvar

As visualizações do lado do cliente são ótimas para UX, mas você também deve validar no servidor antes persistindo um cron job. Chame o endpoint de análise do seu back-end e verifique o isValid bandeira.

async function saveCronJob(name, expression) {
  // Validate the expression before saving
  const res = await fetch("https://api.botoi.com/v1/cron/parse", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ expression }),
  });
  const { data } = await res.json();

  if (!data.isValid) {
    throw new Error("Invalid cron expression: " + expression);
  }

  // Save to your database with the parsed metadata
  await db.cronJobs.create({
    name,
    expression,
    description: data.description,
    nextRun: data.nextRuns[0],
  });

  return { description: data.description, nextRun: data.nextRuns[0] };
}

Quando um usuário envia uma expressão inválida, a API retorna uma resposta limpa na qual você pode agir:

{
  "success": true,
  "data": {
    "isValid": false,
    "description": null,
    "nextRuns": [],
    "parts": null
  }
}

Sem exceções para capturar, sem regex para escrever. Verificar data.isValid e retornar um erro mensagem ao usuário. Você também pode armazenar o description e nextRun ao lado da expressão bruta em seu banco de dados, para que você possa exibi-las em visualizações de listagem sem chamando a API novamente.

Expressões cron comuns e o que a API retorna

Expressão	Descrição
* * * * *	Cada minuto
*/15 * * * *	A cada 15 minutos
0 * * * *	A cada hora
0 9 * * MON-FRI	Às 09:00 de segunda a sexta
0 0 1 * *	À meia-noite do dia 1º de cada mês
30 4 * * SUN	Às 04h30 de domingo
0 9,17 * * *	Às 09:00 e às 17:00 todos os dias
0 0 * * 0	À meia-noite de domingo

Cada uma dessas expressões retorna a mesma resposta estruturada: sinalizador de validade, descrição, próximas execuções e partes analisadas. Você pode usar a tabela acima como casos de teste ao integrar a API.

Por que descarregar a análise do cron para uma API?

• Nenhuma dependência de biblioteca. Existem bibliotecas de análise Cron para todas as linguagens, mas eles adicionam tamanho de pacote (frontend) ou manutenção de dependência (backend). Uma única chamada HTTP substitui a biblioteca.
• Comportamento consistente entre serviços. Se o seu sistema tiver um agendador Node.js, um trabalhador Python e um microsserviço Go, todos analisam expressões cron de maneira diferente. Uma API fornece uma única fonte de verdade.
• Descrições legíveis gratuitamente. Gerando linguagem natural a partir do cron a sintaxe é mais difícil do que analisar o cronograma. A API trata ambos em uma chamada.
• Pré-visualização instantânea para usuários. Respostas de borda abaixo de 50 ms fazem validação em tempo real prático, mesmo em cada pressionamento de tecla com debouncing.