Konvensi

Uang dan volume - string

{
  "balance": "124.30",
  "currency": "USD"
}
{
  "purchased_gb": "25.000",
  "used_gb": "2.566",
  "left_gb": "22.434"
}

Parse sebagai decimal, bukan float. Mata uang - USD. Gigabyte = 10^9 byte.

Waktu

ISO-8601 dengan offset eksplisit, selalu UTC: 2026-08-28T14:03:11+00:00.

Enumerasi yang dapat bertambah

Status pesanan, tipe transaksi, tipe peristiwa, status paket, kind, family dapat bertambah di dalam v1 tanpa pemberitahuan - nilai yang tidak dikenal harus bisa ditangani. Dalam filter, nilai yang tidak dikenal dibaca sebagai “tanpa filter”.

Paginasi

Parameter	Arti
offset	berapa baris yang dilewati; default 0
limit	1..200, default 50 (untuk GET /api/v1/packages - 200)

Keduanya dipangkas, bukan ditolak, dan dikembalikan di body dalam bentuk yang sudah dipangkas. Respons membawa total.

GET /api/v1/orders?limit=100&offset=100
    -> { "orders": [...], "total": 317, "offset": 100, "limit": 100 }

Pada daftar yang terus ditulisi, offset menunjuk posisi: saat mengambil data secara penuh, lakukan deduplikasi berdasarkan id. Urutannya tetap - yang terbaru di atas.

Log peristiwa dibaca secara berbeda: ?after=<id>, respons membawa next_after.

Idempotensi

Operasi yang memotong saldo memerlukan header: POST /api/v1/packages (pembelian), POST /api/v1/packages/{id}/topup (penambahan trafik), dan POST /api/v1/packages/{id}/prolong (perpanjangan alamat).

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

String hingga 255 karakter, spasi di awal dan akhir dipangkas.

Pengulangan dengan kunci yang sama dan body yang sama mengembalikan respons yang sama. Buat kunci sebelum permintaan dan gunakan lagi saat mengulang, termasuk pengulangan setelah timeout.

Kunci diingat selama 24 jam: kunci yang sama setelah satu hari memulai operasi baru.

Penolakan:

• 422 - idempotency_key_required (header tidak ada), idempotency_key_invalid (kosong atau lebih dari 255), idempotency_key_reused (kunci yang sama dengan body berbeda)
• 409 - idempotency_in_progress (permintaan sebelumnya masih berjalan - ulangi sebentar lagi dengan kunci yang sama)
• 500 - operation_indeterminate (pengulangan dengan kunci dari operasi yang hasilnya belum pasti - lihat Penolakan)

Cache katalog geo

Tingkat-tingkat katalog geo mengirim ETag - hash versi katalog yang buram. Kirimkan kembali dalam If-None-Match - Anda akan mendapat 304 tanpa body. Versi yang sama dalam bentuk yang dapat dibaca ada di body sebagai field version.

Pembuatan versi

Dirilis di v1 tanpa pemberitahuan: field baru di respons, parameter opsional baru, nilai baru pada enumerasi yang dapat bertambah, endpoint baru, kode kesalahan baru pada status yang sudah ada.

Hanya dengan versi baru: penghapusan atau penggantian nama field, penyempitan tipe, field wajib baru di permintaan, perubahan status atau kode untuk kasus yang sudah dijelaskan, perubahan nilai default.

Penghentian dukungan (deprecation): header Deprecation dan Sunset, sekurang-kurangnya 6 bulan sebelum dimatikan.