Kimlik Doğrulama ve API Anahtarları

Discuse API, her isteği bir API anahtarıyla doğrular. Anahtarı X-API-Key istek üst bilgisinde (veya JSON gövdesinde api_key alanı olarak) gönderin. Anahtarlar disc_ ön ekiyle başlar, tek bir projeye bağlıdır ve yalnızca oluşturuldukları anda bir kez tam olarak gösterilir. Bu kılavuzda anahtarları nasıl alacağınız, kullanacağınız, güvenceye alacağınız ve yenileyeceğiniz anlatılır.

Discuse kimlik doğrulaması nasıl çalışır?

Her API çağrısı geçerli bir API anahtarı içermelidir. Discuse bu anahtarı şu amaçlarla kullanır:

Kullanımı projenizin kotasına göre izlemek
Kötüye kullanımı önlemek için anahtar bazında hız sınırı uygulamak
İstekleri doğru projeye ve proje ayarlarına bağlamak
Hesabınızın kaynaklarına erişimi kontrol etmek

API Anahtarınızı Alma

1. Adım: Hesap Oluşturun

Henüz yapmadıysanız discuse.com adresinden bir Discuse hesabı oluşturun. Aylık belirli sayıda API isteğinin yanı sıra metin, spam, dil ve görsel kontrollerine erişim içeren ücretsiz Basic planla başlayabilirsiniz. Güncel plan bazlı limitler için fiyatlandırma sayfasına bakın.

2. Adım: Kontrol Paneline Erişin

Giriş yaptıktan sonra kontrol panelinize gidin. Gezinme menüsünde "API Keys" veya "Developer" bölümünü arayın.

3. Adım: Yeni Bir Anahtar Oluşturun

"Create New API Key" seçeneğine tıklayın ve isteğe bağlı olarak anahtar için bir ad veya açıklama girin. Birden fazla anahtar oluşturursanız, bu her bir anahtarın amacını ayırt etmenize yardımcı olur.

Yeni API anahtarınız yalnızca bir kez gösterilir. Hemen kopyalayın ve güvenli bir yerde saklayın; anahtarın tamamını tekrar görüntüleyemezsiniz.

API Anahtarınızı Kullanma

Her istekte API anahtarınızı X-API-Key üst bilgisine ekleyin:

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345" \
  -d '{
    "content": {
      "text": "Content to analyze"
    }
  }'

Alternatif olarak anahtarı üst bilgi yerine JSON gövdesinin içinde api_key alanı olarak da gönderebilirsiniz; ancak anahtarın istek gövdesi günlüklerine düşmemesi için üst bilgi kullanımı tercih edilir.

JavaScript Örneği

const response = await fetch('https://api.discuse.com/api/v2/check', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.DISCUSE_API_KEY
  },
  body: JSON.stringify({
    content: { text: 'Content to analyze' }
  })
});

Python Örneği

import requests
import os

response = requests.post(
    'https://api.discuse.com/api/v2/check',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['DISCUSE_API_KEY']
    },
    json={
        'content': {'text': 'Content to analyze'}
    }
)

API Anahtarı Güvenliği İçin En İyi Uygulamalar

Anahtarları Asla İstemci Tarafı Kodda Açığa Çıkarmayın

API anahtarları, tarayıcıda çalışan JavaScript koduna asla eklenmemelidir. İstemci tarafı kod, sayfa kaynağını görüntüleyen herkes tarafından görülebilir.

// WRONG - Don't do this!
const API_KEY = 'disc_aB3dEf6...'; // Exposed in browser

// CORRECT - Use a backend proxy
const response = await fetch('/api/moderate', {
  method: 'POST',
  body: JSON.stringify({ text: userInput })
});

Ortam Değişkenleri Kullanın

API anahtarlarını kod tabanınızda değil, ortam değişkenlerinde saklayın:

# .env file (add to .gitignore!)
DISCUSE_API_KEY=disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345

// Access in Node.js
const apiKey = process.env.DISCUSE_API_KEY;

Anahtarları Düzenli Olarak Yenileyin

API anahtarlarınızı, özellikle ele geçirilmiş olabileceklerinden şüpheleniyorsanız, düzenli aralıklarla yenileyin:

Yeni bir API anahtarı oluşturun
Uygulamanızı yeni anahtarı kullanacak şekilde güncelleyin
Her şeyin doğru çalıştığını doğrulayın
Eski anahtarı iptal edin

Not: Doğrulanmış anahtarlar önbelleğe alındığı için iptal edilen bir anahtar yaklaşık 5 dakikaya kadar kullanılabilir durumda kalabilir. Anında geçiş beklemek yerine yenileme işlemlerini bu kısa örtüşmeyi dikkate alarak planlayın.

Farklı Ortamlar İçin Ayrı Anahtarlar Kullanın

Geliştirme, hazırlık ve üretim ortamları için farklı API anahtarları oluşturun:

Ortam	Anahtarın Amacı
Geliştirme	Test ve yerel geliştirme
Hazırlık	Üretim öncesi test
Üretim	Canlı uygulama trafiği

Bu sayede ele geçirilmiş bir anahtarı, diğer ortamları etkilemeden iptal edebilirsiniz.

Hız sınırlandırması nasıl çalışır?

Hız sınırlandırması plan bazında değil, API anahtarı bazında uygulanır. Her anahtarın, oluşturulurken belirlenen dakika başına istek (RPM) limiti vardır; siz bir değer belirtmezseniz varsayılan olarak dakikada 60 istek uygulanır. Aynı hesaptaki farklı anahtarlar farklı limitlere sahip olabilir; böylece yüksek trafik işleyen bir servise, tek seferlik bir entegrasyondan daha yüksek RPM verebilirsiniz.

Bir anahtar RPM limitini aştığında istek, hız limitinin aşıldığını belirten bir message içeren HTTP 429 Too Many Requests durumuyla başarısız olur. Hız sınırı sayaçları, kayan bir dakikalık pencereye göre sıfırlanır.

Hız sınırlarını yönetme

429 durumunda (ve geçici 5xx durumlarında) geri çekilip yeniden deneyin. Pencere bir dakika olduğu için, yaklaşık bir saniyeden başlayıp artan üstel geri çekilme yöntemi iyi sonuç verir:

async function checkWithRetry(content, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('https://api.discuse.com/api/v2/check', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.DISCUSE_API_KEY
      },
      body: JSON.stringify({ content })
    });

    if (response.status === 429 || response.status >= 500) {
      const delay = 1000 * Math.pow(2, attempt); // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response.json();
  }
  throw new Error('Max retries exceeded');
}

Hangi hata yanıtlarını alabilirim?

Durum	HTTP durumu
Hatalı biçimlendirilmiş istek (boş içerik, 10.000 karakteri aşan metin, çok fazla URL)	`400` istek doğrulama
Eksik veya geçersiz API anahtarı	`401`
Anahtar için hız limiti aşıldı	`429`
Faturalandırma dönemi kotası tükendi	`200` ve beraberinde `message` ile `usage` (hata durumu değildir)

Kota tükenmesi özellikle bir HTTP hatası olarak ele alınmaz: /api/v2/check yanıtı yine 200 döndürür; has_violations: false, tükenen kotayı açıklayan bir message ve api_requests_remaining: 0 değerini gösteren bir usage nesnesi içerir. Durum koduna güvenmek yerine bu alanları kontrol edin. Kimlik doğrulama hataları 401, hız sınırları 429, istek doğrulama hataları ise 400 döndürür. Tam liste için Hata ve Yanıt Kodları referansına bakın.

Birden Fazla Anahtarı Yönetme

Daha büyük ekipler veya karmaşık uygulamalar için birden fazla API anahtarına ihtiyaç duyabilirsiniz:

Birden Fazla Anahtar İçin Kullanım Senaryoları

Ortam bazlı anahtarlar: Geliştirme, hazırlık ve üretim için ayrı anahtarlar
Servis bazlı anahtarlar: Farklı mikro servisler için farklı anahtarlar
Ekip bazlı anahtarlar: İç faturalandırma için kullanımı ekibe göre izole etme
Geçici anahtarlar: Yükleniciler veya entegrasyonlar için kısa ömürlü anahtarlar

Anahtar Yönetimi İçin En İyi Uygulamalar

Anahtarlara açıklayıcı adlar verin: "Production - User Service", "Staging - Backend"
Anahtar kullanımını belgeleyin: Hangi anahtarın nerede kullanıldığını kaydedin
Uyarılar kurun: Olağan dışı kullanım kalıplarını izleyin
Düzenli denetimler yapın: Kullanılmayan anahtarları üç ayda bir gözden geçirip temizleyin

Sonraki Adımlar

Hızlı Başlangıç Kılavuzu - İlk API çağrınızı yapın
Metin Analizi - Duygu tespiti hakkında bilgi edinin
İçerik Moderasyonunu Ölçeklendirme - Yüksek hacimli uygulama desenleri