Unix Timestamp vs String Datetime di API — Mana yang Sebaiknya Dipakai?

Setiap API yang berurusan dengan waktu harus memilih: merepresentasikan tanggal/waktu sebagai Unix timestamp (angka bulat) atau sebagai string datetime terformat (misalnya ISO 8601). Keduanya bisa dipakai. Keduanya umum. Tapi perilakunya berbeda, dan pilihan ini akan berdampak ke semua klien yang memakai API Anda.

Artikel ini membahas trade-off‑nya supaya Anda bisa mengambil keputusan dengan sadar — atau setidaknya paham format apa yang sedang Anda hadapi saat mengonsumsi API yang sudah ada.

Untuk cek cepat dan konversi, Unix Timestamp Converter bisa menangani kedua format.

Contoh formatnya seperti apa

Unix timestamp (integer, detik): ` 1712505600 `

Unix timestamp (integer, milidetik): ` 1712505600000 `

String datetime ISO 8601 (UTC): ` 2024-04-07T16:00:00Z `

String datetime ISO 8601 (dengan offset timezone): ` 2024-04-07T12:00:00-04:00 `

RFC 2822 (umum di header email, API lama): ` Sun, 07 Apr 2024 16:00:00 +0000 `

Alasan memilih Unix timestamp

Tanpa ambiguitas timezone

Unix timestamp selalu UTC. Tidak ada komponen timezone yang harus ditafsirkan, tidak ada offset yang harus di-parse, dan tidak ada risiko salah membaca singkatan timezone. 1712505600 selalu berarti satu momen yang sama, di mana pun server atau klien berjalan.

Ini argumen terkuat untuk komunikasi backend‑ke‑backend. Penanganan timezone adalah salah satu sumber bug tanggal yang paling sering. Timestamp “menghindari” masalah itu sepenuhnya.

Aritmetika sederhana

Membandingkan dua timestamp, menghitung selisih, mengecek masa berlaku, menambah 24 jam — semuanya jadi operasi integer yang sederhana.

// Apakah token sudah kedaluwarsa?
const isExpired = Date.now() / 1000 > tokenExp;

// Tambah 24 jam ke timestamp
const tomorrow = now + 86400;

Kalau memakai string datetime, operasi yang sama butuh parsing, normalisasi timezone, dan pemanggilan library tanggal.

Ringkas dan mudah diurutkan

Timestamp ringkas — 10 digit untuk detik, 13 digit untuk milidetik — dan bisa diurutkan dengan benar sebagai integer. String datetime hanya akan terurut benar sebagai string jika formatnya ISO 8601 (YYYY-MM-DD...). Format lain seperti “April 7, 2024” atau “07/04/2024” tidak akan terurut dengan benar tanpa parsing.

Penyimpanan lebih efisien

Integer biasanya 4 atau 8 byte di kolom database. String datetime di kolom VARCHAR bisa 20–30 byte. Untuk tabel besar dengan jutaan baris, perbedaan ini nyata.

Alasan memilih string datetime

Mudah dibaca manusia tanpa konversi

Saat Anda melihat respons API di browser, log, atau alat debugging, 2024-04-07T16:00:00Z langsung “kebaca”. 1712505600 tidak berarti apa‑apa tanpa konversi.

Ini perbedaan kualitas hidup yang nyata saat development dan debugging. Kalau field created_at berisi 1712505600, Anda biasanya harus menempelkannya ke converter untuk memastikan benar. Kalau berisi 2024-04-07T16:00:00Z, Anda bisa paham sekilas.

Representasi waktu lokal

String datetime bisa membawa offset timezone: 2024-04-07T12:00:00-04:00. Ini berguna untuk event yang memang terkait waktu lokal — rapat jam 9 pagi di New York, jam operasional bisnis, atau jadwal keberangkatan penerbangan.

Unix timestamp bisa menyimpan momen yang sama, tetapi “waktu lokal” harus direkonstruksi saat ditampilkan menggunakan metadata timezone yang disimpan terpisah. String datetime bisa membawa offset‑nya langsung.

Interoperabilitas lebih baik dengan library tanggal

Banyak framework frontend dan library tanggal dapat mem-parse ISO 8601 secara native. JavaScript new Date("2024-04-07T16:00:00Z") langsung jalan. Python datetime.fromisoformat() juga langsung bisa. Developer experience biasanya lebih mulus.

Lebih mudah divalidasi

String datetime punya struktur yang terlihat. Kalau formatnya salah, biasanya mudah ketahuan. 2024-13-07T16:00:00Z jelas bulan 13 tidak valid. Sementara Unix timestamp seperti 17125056000 (kelebihan satu nol) lebih sulit dikenali salah tanpa tahu rentang yang seharusnya.

Jebakan yang paling sering terjadi

Bingung detik vs milidetik

Unix timestamp bisa dalam detik atau milidetik, dan tidak semua sistem sepakat. JavaScript memakai milidetik (Date.now() menghasilkan angka 13 digit). Mayoritas bahasa backend dan database memakai detik (10 digit). Kalau frontend JavaScript mengirim timestamp ke backend yang mengharapkan detik, nilainya jadi 1.000× lebih besar — hasilnya tanggal bisa berada di tahun 55.000.

Solusinya: dokumentasikan unit yang dipakai (detik atau milidetik) secara eksplisit. Unix Timestamp Converter bisa mendeteksi format berdasarkan jumlah digit — berguna untuk debugging cepat.

String datetime “naif” (tanpa timezone)

String datetime tanpa penanda timezone — 2024-04-07 16:00:00 — itu ambigu. Apakah UTC? Waktu lokal server? Waktu lokal user? Library yang berbeda menangani ini dengan cara berbeda dan sering mengejutkan.

Selalu pakai string datetime yang timezone‑aware di respons API. 2024-04-07T16:00:00Z (UTC) atau 2024-04-07T12:00:00-04:00 (offset eksplisit) — jangan pernah kirim waktu lokal “telanjang” tanpa keterangan.

Perbedaan parsing antar bahasa

ISO 8601 adalah standar, tetapi tidak semua implementasi bisa mem-parse semua variasi ISO 8601 yang valid. Varian mikrodetik (2024-04-07T16:00:00.123456Z) valid, tetapi tidak semua parser mendukung. Pemisah T kadang bisa diganti spasi (2024-04-07 16:00:00Z) — valid di SQL namun tidak selalu diterima parser ISO 8601 yang ketat.

Kalau Anda memakai string datetime, uji bahwa formatnya bisa diparse dengan benar di semua bahasa dan library yang dipakai klien Anda.

Praktik yang paling umum di API produksi

Konvensi yang dominan di REST API modern adalah string datetime ISO 8601 dalam UTC untuk field yang sering dilihat manusia (created_at, updated_at, published_at) dan Unix timestamp dalam detik untuk field autentikasi/keamanan (exp, iat, nbf di JWT, masa berlaku token).

Kombinasi ini masuk akal: field yang dilihat manusia diuntungkan oleh keterbacaan; field keamanan diuntungkan oleh operasi integer yang ringkas dan minim parsing.

API GitHub memakai string ISO 8601. Stripe memakai Unix timestamp. Twilio memakai ISO 8601. Twitter/X memakai Unix milidetik. Tidak ada standar tunggal di industri — Anda akan menemui keduanya.

Kerangka keputusan sederhana

Pilih Unix timestamp jika:

Anda menyimpan/mengirim timestamp terutama untuk komputasi (sorting, aritmetika, cek kedaluwarsa)
Konteksnya backend‑ke‑backend, dan keterbacaan manusia tidak terlalu penting
Anda butuh penyimpanan ringkas dan perbandingan sederhana
Anda ingin menghindari masalah timezone sepenuhnya

Pilih string datetime ISO 8601 jika:

Timestamp akan sering dibaca developer saat debugging respons API
Waktunya terkait timezone atau konteks lokal tertentu
Anda membuat public API dan developer experience itu penting
Anda perlu mewakili waktu dengan presisi sub‑detik secara andal

Apa pun yang Anda pilih, dokumentasikan dengan jelas: unitnya (detik atau milidetik untuk timestamp), timezonenya (timestamp selalu UTC; untuk string sertakan offset), dan formatnya (varian ISO 8601 untuk string). Ambiguitas dalam representasi waktu hampir pasti akan melahirkan bug yang sulit dilacak.