API yang baik terasa membosankan dengan cara yang positif: URL yang bisa ditebak, error yang jujur, skema kecil dan stabil, tanpa kejutan. Inilah prinsip-prinsip yang membentuk Noxyr Server API, diambil dari standar industri di balik Stripe, Resend, OpenAI, dan API resmi Discord.
1. URL dengan versi
Setiap endpoint berada di bawah /api/v1/. Saat kami menambahkan perubahan yang tidak kompatibel, perubahan itu masuk ke /api/v2/, sehingga integrasi lama tetap berjalan. Discord melakukan hal yang sama dengan /api/v10/. Jika API tidak diberi versi, setiap perubahan skema akan berujung menjadi tiket dukungan pelanggan.
2. Resource dulu, aksi kemudian
Endpoint Noxyr dinamai dengan kata benda: server, tickets, activity, invoices, reviews, giveaways. Semuanya hanya-baca, semuanya GET. Saat kami menambahkan penulisan data, itu akan berupa POST/PATCH/DELETE pada resource yang sama. Ini sejalan dengan konvensi REST dan membuat model mental tetap sederhana.
3. Bearer token, satu rahasia
Autentikasi memakai Authorization: Bearer nxr_.... Tidak ada request yang ditandatangani, dan tidak ada alur OAuth untuk data server yang hanya-baca. Banyak API modern untuk developer memakai pola ini karena bisa dipakai di mana saja: curl, browser, Postman, serverless edge. Discord juga memakai bearer token untuk pengguna yang diotorisasi lewat OAuth; polanya sudah umum.
4. Simpan hanya hash
Setiap kunci Noxyr di-hash dengan SHA-256 di sisi server. Nilai aslinya ditampilkan sekali saat kunci dibuat dan tidak pernah ditampilkan lagi. Jika database kami bocor, tidak ada kunci yang bisa dipakai. Stripe, GitHub, Resend, dan setiap vendor API yang dikelola dengan baik melakukan hal yang sama; penyimpanan kunci yang bisa dibalik adalah tanda bahaya.
5. Scope yang terperinci
Satu kunci, enam sakelar yang berdiri sendiri. Review adalah data publik, sedangkan penjualan bersifat privat. Dengan memisahkannya, Anda bisa membagikan kunci khusus review kepada mitra pemasaran dan tetap menyembunyikan angka pendapatan di balik sakelar lain. Perubahan scope langsung berlaku (diperiksa pada setiap request), sehingga pencabutan akses tidak perlu rotasi kunci.
6. Respons error yang jujur
Setiap error berupa JSON dengan kode mesin yang stabil dan pesan yang bisa dibaca manusia:
{ "error": "scope_disabled", "message": "Scope \"tickets\" dimatikan untuk kunci ini. Aktifkan di halaman API dashboard." }Kode mesin memudahkan retry dan dashboard. Pesan yang bisa dibaca manusia mempercepat debugging. Lonjakan pencarian "discord increased api errors" pada Juli 2026 (Google Trends "breakout") menunjukkan apa yang terjadi saat error tidak jelas: pengguna mulai menebak-nebak.
7. Deret waktu tanpa celah
Endpoint /api/v1/activity mengembalikan setiap hari dalam rentang yang diminta, bahkan saat jumlahnya nol. Frontend tidak perlu mengisi celah, dan grafik tidak melompat-lompat di antara tanggal yang jarang. Ini hal kecil dengan dampak besar pada kenyamanan pemakaian.
8. Rate limit dengan header
Setiap respons membawa header RateLimit-* agar client bisa mundur sebelum terkena 429. Ini mengikuti format draf IETF yang sudah distandarkan, bentuknya sama seperti GitHub dan API modern lainnya, sehingga library client yang sudah mendukung format ini langsung bisa dipakai.
9. CORS yang longgar untuk data hanya-baca
Endpoint hanya-baca mengirim Access-Control-Allow-Origin: *. Karena yang mengautentikasi adalah kunci, bukan origin, membuka CORS tidak menambah risiko keamanan dan memungkinkan alat berbasis browser memanggil API secara langsung, tanpa proxy tambahan dan tanpa trik localhost.
10. Skema kecil dan stabil
Setiap respons muat dalam satu layar. Tidak ada objek bersarang yang opsional, tidak ada field yang hanya muncul ketika feature flag aktif. Skema kecil mudah di-cache, mudah diuji, dan mudah diketik di TypeScript.
Lihat contohnya: Tutorial Server API. Dan saat Discord sendiri sedang bermasalah, lihat arti sebenarnya dari error API Discord tersebut.