Analyser et valider les expressions cron via l'API REST

Vous créez un panneau d'administration dans lequel les utilisateurs planifient des tâches récurrentes. Ils tapent une expression cron dans un champ de texte, appuyez sur Enregistrer et attendez que le système fasse la bonne chose. Le problème : la syntaxe cron est énigmatique. */15 * * * * c'est assez clair, mais qu'en est-il 0 9 1-15 * 1-5? La plupart des utilisateurs (et de nombreux développeurs) ne peuvent pas lire cela d'un seul coup d'œil.

Vous devez montrer aux utilisateurs ce que signifie leur expression *avant* de l'enregistrer. Une description comme "À 9h00 les jours 1 à 15, du lundi au vendredi" vaut plus qu'une info-bulle reliant vers crontab.guru.

L'API de l'analyseur cron de Botoi fait trois choses dans une seule requête POST : valide l'expression, génère une description lisible par l'homme et renvoie les prochaines heures d'exécution planifiées. Pas de cron bibliothèques à installer, aucune logique d'analyse à maintenir.

Le point final de l'analyse

Envoyer une expression cron à /v1/cron/parse et obtenez une ventilation structurée.

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

Réponse:

{
  "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 réponse comprend tout ce dont vous avez besoin : un isValid drapeau, un anglais simple description, les cinq prochaines heures d'exécution en UTC et l'individu parts répartis par domaine. Vous pouvez afficher la description directement dans votre UI et utiliser le nextRuns tableau pour afficher un aperçu des exécutions à venir.

Obtenez plus de courses à venir

Si vous avez besoin de plus de cinq dates d'avant-première, ou si vous ne vous souciez que du calendrier et non du description, utilisez le /v1/cron/next point final. Passer un count paramètre pour contrôler le nombre de temps d'exécution futurs que vous récupérez.

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

Réponse:

{
  "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"
    ]
  }
}

Notez l'écart entre le 27 mars (vendredi) et le 30 mars (lundi). L'expression 0 9 * * MON-FRI saute les week-ends, et l'API le reflète correctement.

Créer un widget d'aperçu cron

Voici comment câbler le point de terminaison d’analyse dans un champ de saisie frontal. Lorsque l'utilisateur tape un cron expression, le widget appelle l'API et affiche la description et les exécutions à venir en temps réel.

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>
    \

Pour une utilisation en production, ajoutez un anti-rebond (200 à 300 ms) afin de ne pas déclencher de requête à chaque frappe. L'API répond en moins de 50 ms depuis la périphérie de Cloudflare, de sorte que l'aperçu semble instantané une fois le la demande est envoyée.

Version Réagir/Préagir

Si vous utilisez React ou Preact, voici un composant qui intègre la même logique avec un AbortController pour annuler les demandes obsolètes.

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

Valider la saisie de l'utilisateur avant d'enregistrer

Les aperçus côté client sont parfaits pour l'UX, mais vous devez également valider sur le serveur avant persister un travail cron. Appelez le point de terminaison d'analyse depuis votre backend et vérifiez le isValid drapeau.

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

Lorsqu'un utilisateur soumet une expression non valide, l'API renvoie une réponse claire sur laquelle vous pouvez agir :

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

Aucune exception à détecter, aucune regex à écrire. Vérifier data.isValid et renvoie une erreur message à l'utilisateur. Vous pouvez également stocker le description et nextRun à côté de l'expression brute dans votre base de données, afin que vous puissiez les afficher dans des vues de liste sans appeler à nouveau l'API.

Expressions cron courantes et ce que renvoie l'API

Expression	Description
* * * * *	Chaque minute
*/15 * * * *	Toutes les 15 minutes
0 * * * *	Toutes les heures
0 9 * * MON-FRI	À 09h00 du lundi au vendredi
0 0 1 * *	À minuit le 1er de chaque mois
30 4 * * SUN	À 04h30 le dimanche
0 9,17 * * *	À 09h00 et 17h00 tous les jours
0 0 * * 0	Dimanche à minuit

Chacune de ces expressions renvoie la même réponse structurée : indicateur de validité, description, prochaines exécutions et pièces analysées. Vous pouvez utiliser le tableau ci-dessus comme cas de test lors de l'intégration de l'API.

Pourquoi confier l'analyse cron à une API ?

• Aucune dépendance à la bibliothèque. Les bibliothèques d'analyse Cron existent pour chaque langage, mais ils ajoutent la taille du bundle (frontend) ou la maintenance des dépendances (backend). Un seul appel HTTP remplace la bibliothèque.
• Comportement cohérent entre les services. Si votre système dispose d'un planificateur Node.js, un travailleur Python et un microservice Go, ils analysent tous les expressions cron différemment. Une API vous donne une source unique de vérité.
• Descriptions lisibles par l'homme gratuitement. Générer un langage naturel à partir de cron la syntaxe est plus difficile que l'analyse du calendrier. L'API gère les deux en un seul appel.
• Aperçu instantané pour les utilisateurs. Les réponses de bord inférieures à 50 ms permettent une validation en temps réel pratique, même à chaque frappe avec anti-rebond.