Analizar y validar expresiones cron a través de la API REST

Estás creando un panel de administración donde los usuarios programan trabajos recurrentes. Escriben una expresión cron en un campo de texto, presione guardar y espere que el sistema haga lo correcto. El problema: la sintaxis cron es críptico. */15 * * * * Está bastante claro, pero ¿qué pasa? 0 9 1-15 * 1-5? La mayoría de los usuarios (y muchos desarrolladores) no pueden leer eso de un vistazo.

Debes mostrar a los usuarios lo que significa su expresión *antes* de guardarla. Una descripción como "A las 09:00 los días 1 a 15, de lunes a viernes" vale más que un enlace de información sobre herramientas a crontab.guru.

La API del analizador cron de Botoi hace tres cosas en una sola solicitud POST: valida la expresión, genera una descripción legible por humanos y devuelve los siguientes tiempos de ejecución programados. Sin cron bibliotecas para instalar, sin lógica de análisis que mantener.

El punto final del análisis

Enviar una expresión cron a /v1/cron/parse y recuperar un desglose estructurado.

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

Respuesta:

{
  "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": "*"
    }
  }
}

La respuesta incluye todo lo que necesitas: un isValid bandera, un inglés sencillo description, los próximos cinco tiempos de ejecución en UTC y el individuo parts desglosado por campo. Puede mostrar la descripción directamente en su interfaz de usuario y utilizar el nextRuns matriz para mostrar una vista previa de las próximas ejecuciones.

Obtenga más carreras próximas

Si necesitas más de cinco fechas previas, o solo te importa el calendario y no el descripción, utilice el /v1/cron/next punto final. pasar un count parámetro para controlar cuántos tiempos de ejecución futuros obtendrás.

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

Respuesta:

{
  "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 la brecha entre el 27 de marzo (viernes) y el 30 de marzo (lunes). la expresión 0 9 * * MON-FRI se salta los fines de semana y la API lo refleja correctamente.

Crear un widget de vista previa de cron

A continuación se explica cómo conectar el punto final de análisis a un campo de entrada de interfaz. Mientras el usuario escribe un cron expresión, el widget llama a la API y muestra la descripción y las próximas ejecuciones en tiempo 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 en producción, agregue un rebote (200-300 ms) para no generar una solicitud con cada pulsación de tecla. La API responde en menos de 50 ms desde el borde de Cloudflare, por lo que la vista previa se siente instantánea una vez que la solicitud sale.

Versión reaccionar/preact

Si está utilizando React o Preact, aquí hay un componente que envuelve la misma lógica con un AbortController para cancelar solicitudes 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>
  );
}

Validar la entrada del usuario antes de guardar

Las vistas previas del lado del cliente son excelentes para la UX, pero también debes validarlas en el servidor antes. persistir un trabajo cron. Llame al punto final de análisis desde su backend y verifique el isValid bandera.

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] };
}

Cuando un usuario envía una expresión no válida, la API devuelve una respuesta limpia sobre la que puede actuar:

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

No hay excepciones que capturar, ni expresiones regulares que escribir. Controlar data.isValid y devolver un error mensaje al usuario. También puedes almacenar el description y nextRun junto con la expresión sin formato en su base de datos, para que pueda mostrarlos en vistas de listado sin llamando a la API nuevamente.

Expresiones cron comunes y lo que devuelve la API

Expresión	Descripción
* * * * *	cada minuto
*/15 * * * *	Cada 15 minutos
0 * * * *	Cada hora
0 9 * * MON-FRI	A las 09:00 de lunes a viernes
0 0 1 * *	A medianoche del día 1 de cada mes.
30 4 * * SUN	A las 04:30 del domingo
0 9,17 * * *	A las 09:00 y 17:00 todos los días
0 0 * * 0	A medianoche del domingo

Cada una de estas expresiones devuelve la misma respuesta estructurada: indicador de validez, descripción, próximas ejecuciones y partes analizadas. Puede utilizar la tabla anterior como casos de prueba al integrar la API.

¿Por qué descargar el análisis cron a una API?

• Sin dependencia de la biblioteca. Existen bibliotecas de análisis cron para todos los idiomas, pero agregan tamaño de paquete (frontend) o mantenimiento de dependencia (backend). Una sola llamada HTTP reemplaza la biblioteca.
• Comportamiento consistente en todos los servicios. Si su sistema tiene un programador Node.js, un trabajador de Python y un microservicio de Go, todos analizan las expresiones cron de manera diferente. Una API le ofrece una única fuente de verdad.
• Descripciones legibles por humanos de forma gratuita. Generando lenguaje natural desde cron La sintaxis es más difícil que analizar el cronograma. La API maneja ambos en una sola llamada.
• Vista previa instantánea para las usuarias. Las respuestas de borde por debajo de 50 ms realizan una validación en tiempo real práctico, incluso en cada pulsación de tecla con antirrebote.