Parsing dan validasi ekspresi cron melalui REST API

Anda sedang membangun panel admin tempat pengguna menjadwalkan pekerjaan berulang. Mereka mengetikkan ekspresi cron ke dalam kolom teks, tekan simpan, dan harapkan sistem melakukan hal yang benar. Masalahnya: sintaks cron adalah samar. */15 * * * * cukup jelas, tapi bagaimana dengan 0 9 1-15 * 1-5? Sebagian besar pengguna (dan banyak pengembang) tidak dapat membacanya secara sekilas.

Anda perlu menunjukkan kepada pengguna apa arti ekspresi mereka *sebelum* mereka menyimpannya. Deskripsi seperti "Pada pukul 09:00 pada hari 1 hingga 15, Senin hingga Jumat" lebih berharga daripada tautan tooltip ke crontab.guru.

API cron parser Botoi melakukan tiga hal dalam satu permintaan POST: memvalidasi ekspresi, menghasilkan deskripsi yang dapat dibaca manusia, dan mengembalikan waktu berjalan terjadwal berikutnya. Tidak ada cron perpustakaan untuk diinstal, tidak ada logika parsing yang harus dipertahankan.

Titik akhir penguraian

Kirim ekspresi cron ke /v1/cron/parse dan mendapatkan kembali rincian terstruktur.

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

Tanggapan:

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

Responsnya mencakup semua yang Anda perlukan: an isValid bendera, bahasa Inggris biasa description, lima waktu berjalan berikutnya dalam UTC, dan waktu individu parts dibagi berdasarkan bidang. Anda dapat menampilkan deskripsi langsung di UI Anda dan menggunakan nextRuns array untuk menampilkan pratinjau eksekusi yang akan datang.

Dapatkan lebih banyak proses mendatang

Jika Anda memerlukan lebih dari lima tanggal pratinjau, atau Anda hanya peduli pada jadwal dan bukan tanggalnya deskripsi, gunakan /v1/cron/next titik akhir. Lulus a count parameter untuk mengontrol berapa kali waktu berjalan di masa depan yang Anda dapatkan kembali.

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

Tanggapan:

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

Perhatikan kesenjangan antara 27 Maret (Jumat) dan 30 Maret (Senin). Ekspresi 0 9 * * MON-FRI melewatkan akhir pekan, dan API mencerminkannya dengan benar.

Buat widget pratinjau cron

Berikut cara menyambungkan titik akhir parsing ke kolom input frontend. Saat pengguna mengetik cron ekspresi, widget memanggil API dan menampilkan deskripsi dan proses yang akan datang secara real time.

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

Untuk penggunaan produksi, tambahkan debounce (200-300 md) sehingga Anda tidak mengaktifkan permintaan pada setiap penekanan tombol. API merespons dalam waktu kurang dari 50 md dari tepi Cloudflare, sehingga pratinjau terasa instan sekali permintaan keluar.

Versi Bereaksi / Preaksi

Jika Anda menggunakan React atau Preact, berikut adalah komponen yang menggabungkan logika yang sama dengan sebuah AbortController untuk membatalkan permintaan basi.

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

Validasi input pengguna sebelum menyimpan

Pratinjau sisi klien sangat bagus untuk UX, tetapi Anda juga harus memvalidasi di server sebelumnya mempertahankan pekerjaan cron. Panggil titik akhir parse dari backend Anda dan periksa isValid bendera.

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

Saat pengguna mengirimkan ekspresi yang tidak valid, API akan mengembalikan respons bersih yang dapat Anda tindak lanjuti:

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

Tidak ada pengecualian untuk ditangkap, tidak ada regex untuk ditulis. Memeriksa data.isValid dan mengembalikan kesalahan pesan kepada pengguna. Anda juga dapat menyimpan description Dan nextRun di samping ekspresi mentah di database Anda, sehingga Anda dapat menampilkannya dalam tampilan daftar tanpa memanggil API lagi.

Ekspresi cron yang umum dan apa yang dikembalikan oleh API

Ekspresi	Keterangan
* * * * *	Setiap menit
*/15 * * * *	Setiap 15 menit
0 * * * *	Setiap jam
0 9 * * MON-FRI	Pukul 09.00 pada hari Senin sampai Jumat
0 0 1 * *	Pada tengah malam pada tanggal 1 setiap bulan
30 4 * * SUN	Pukul 04:30 pada hari Minggu
0 9,17 * * *	Pukul 09.00 dan 17.00 setiap hari
0 0 * * 0	Pada tengah malam pada hari Minggu

Masing-masing ekspresi ini mengembalikan respons terstruktur yang sama: tanda validitas, deskripsi, berjalan selanjutnya, dan menguraikan bagian-bagiannya. Anda dapat menggunakan tabel di atas sebagai kasus uji saat mengintegrasikan API.

Mengapa memindahkan penguraian cron ke API?

• Tidak ada ketergantungan perpustakaan. Perpustakaan parsing cron ada untuk setiap bahasa, namun mereka menambahkan ukuran bundel (frontend) atau pemeliharaan ketergantungan (backend). Satu panggilan HTTP menggantikan perpustakaan.
• Perilaku yang konsisten di seluruh layanan. Jika sistem Anda memiliki penjadwal Node.js, seorang pekerja Python, dan layanan mikro Go, semuanya mengurai ekspresi cron secara berbeda. Satu API memberi Anda satu sumber kebenaran.
• Deskripsi yang dapat dibaca manusia secara gratis. Menghasilkan bahasa alami dari cron sintaksis lebih sulit daripada menguraikan jadwal. API menangani keduanya dalam satu panggilan.
• Pratinjau instan untuk pengguna. Respons tepi sub-50ms membuat validasi real-time praktis, bahkan pada setiap penekanan tombol dengan debouncing.