İyi bir API, en iyi anlamda sıkıcı hissettirir: öngörülebilir URL'ler, dürüst hatalar, küçük ve kararlı şemalar, sürpriz yok. Bunlar, Noxyr Server API'sini şekillendiren ilkelerdir ve Stripe, Resend, OpenAI ile resmi Discord API'sinin arkasındaki sektör standartlarından alınmıştır.
1. Sürümlü URL'ler
Her uç nokta /api/v1/ altında yer alır. Geriye dönük uyumsuz değişiklikler eklediğimizde bunlar /api/v2/ altına gider: eski entegrasyonlar çalışmaya devam eder. Discord da aynısını /api/v10/ ile yapar. API'niz sürümlenmiyorsa, her şema değişikliği bir müşteri destek talebine dönüşür.
2. Önce kaynaklar, sonra eylemler
Noxyr uç noktaları isimlere göre adlandırılır: server, tickets, activity, invoices, reviews, giveaways. Hepsi salt okunurdur, hepsi GET. Yazma işlemleri eklediğimizde aynı kaynaklar üzerinde POST/PATCH/DELETE olarak gelecekler. Bu, REST kurallarıyla temiz biçimde örtüşür ve zihinsel modeli küçük tutar.
3. Bearer token'lar, tek bir sır
Kimlik doğrulama Authorization: Bearer nxr_... ile yapılır. Salt okunur sunucu verileri için imzalı istekler ya da OAuth akışı yoktur. Geliştiricilere yönelik modern API'ler bu modelde birleşiyor, çünkü her yerde çalışır: curl, tarayıcılar, Postman, sunucusuz uç sistemler. Discord, OAuth ile yetki verilmiş kullanıcılar için de bearer token kullanır; bu desen evrenseldir.
4. Yalnızca hash'leri sakla
Her Noxyr anahtarı sunucu tarafında SHA-256 ile hash'lenir. Ham değer, üretildiği anda bir kez gösterilir ve bir daha gösterilmez. Veritabanımız sızsa bile hiçbir anahtar kullanılabilir olmaz. Stripe, GitHub, Resend ve iyi yönetilen diğer tüm API sağlayıcıları bunu yapar; anahtarların geri çevrilebilir şekilde saklanması bir kırmızı bayraktır.
5. İnce taneli kapsamlar
Tek anahtar, altı bağımsız seçenek. Yorumlar herkese açık veridir, satışlar ise özeldir. Bunları ayırmak, yalnızca yorumları içeren bir anahtarı bir pazarlama ortağıyla paylaşıp gelir rakamlarını başka bir seçeneğin arkasında tutabileceğiniz anlamına gelir. Kapsam değişiklikleri anında etkili olur (her istekte kontrol edilir), dolayısıyla iptal için anahtar yenilemeye gerek kalmaz.
6. Dürüst hata yanıtları
Her hata, kararlı bir makine kodu ve insanın okuyabileceği bir mesaj içeren JSON'dur:
{ "error": "scope_disabled", "message": "The \"tickets\" scope is turned off for this key. Enable it on the dashboard API page." }Makine tarafından okunabilir kodlar yeniden denemeleri ve panoları kolaylaştırır. İnsan tarafından okunabilir mesajlar ise hata ayıklamayı hızlandırır. Temmuz 2026'da "discord increased api errors" aramalarında görülen Google Trends "breakout" artışı, hatalar belirsiz olduğunda ne olduğunu gösteriyor: kullanıcılar tahmin yürütmeye başlıyor.
7. Sıfırla doldurulmuş zaman serileri
/api/v1/activity uç noktası, sayı sıfır olsa bile istenen aralıktaki her günü döndürür. Frontend'lerin boşlukları doldurmasına gerek kalmaz; grafikler seyrek tarihler arasında zıplamaz. Küçük bir kolaylık gibi görünür, ama hayatı kolaylaştırması çok büyüktür.
8. Başlıklarla hız sınırları
Her yanıt, istemcilerin 429 hatasına ulaşmadan geri çekilebilmesi için RateLimit-* başlıklarını taşır. Bu, standart IETF taslak formatıdır; GitHub ve diğer modern API'lerle aynı yapıdadır, dolayısıyla bu formatı destekleyen mevcut her istemci kütüphanesi kutudan çıktığı gibi çalışır.
9. Salt okunur veriler için serbest CORS
Salt okunur uç noktalar Access-Control-Allow-Origin: * gönderir. Kimliği doğrulayan şey kaynak (origin) değil anahtar olduğu için CORS'u açmanın güvenlik açısından bir maliyeti yoktur ve tarayıcı araçlarının API'yi doğrudan çağırmasına izin verir: proxy iskeleti yok, localhost geçici çözümü yok.
10. Küçük, kararlı şemalar
Her yanıt tek bir ekrana sığar. İç içe geçmiş isteğe bağlı nesneler yok, bir özellik bayrağı açıkken ortaya çıkan alanlar yok. Küçük şemalar önbelleğe alınabilir, test edilebilir ve TypeScript'te kolayca tiplendirilebilir.
Pratikte görmek için: Server API eğitimi. Discord'un kendisi sorun yaşadığında ise o Discord API hatalarının gerçekte ne anlama geldiğine bakın.