Wordly API ile oluşturun.

Hızlı başlangıç

Ücretsiz bir hesap oluşturun, altı haneli kodu kullanarak e-postanızı doğrulayın ve geliştirici kontrol panelinizde bir kez gösterilen API anahtarını kopyalayın.

1. 1
   Hesap oluştur

   Yalnızca e-posta adresi ve şifreyle kaydolun.

2. 2
   E-postanızı doğrulayın

   tarafından gönderilen kodu girin [email protected]. Doğrulama sonrasında 50 ücretsiz kredi verilir.

3. 3
   API anahtarınızı saklayın

   Oluşturulanı kopyala wly_live_... anahtarını kullanın ve onu sunucu tarafı ortam değişkeninde tutun.

4. 4
   Test isteğinde bulunun

   Kimlik doğrulamayı doğrulamak ve kalan bakiyeyi görmek için hesap uç noktasını arayın.

curl "https://api.wordlyenglish.com/v1/account" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Accept: application/json"

{
  "data": {
    "message": "Authenticated",
    "credits_remaining": 50
  },
  "meta": { "lang": "en" }
}

Temel URL ve sürüm oluşturma

Tüm üretim uç noktalarına aşağıdaki sürüme sahip temel URL'den hizmet verilir:

Yanıt veya davranış değişikliklerini kırmak için yeni bir yol sürümü kullanılacaktır. İlave alanlar eklenebilir v1, bu nedenle istemciler tanımadıkları yanıt alanlarını yok saymalıdır.

Kimlik doğrulama

Kimliği doğrulanmış uç noktalar, HTTP'de bir API anahtarı gerektirir Authorization Taşıyıcı şemasını kullanarak başlık.

Authorization: Bearer wly_live_your_api_key

Yerelleştirilmiş API mesajları

Yanıt dilini şununla ayarlayın: ?lang=tr veya standart Accept-Language başlık. Sorgu parametreleri önceliklidir. Her JSON yanıtı, seçilen yerel ayarı bildirir. Content-Language ve meta.lang. Programatik kullanım için hata kodları İngilizce ve sabit kalır; yalnızca okunabilir mesaj yerelleştirilir.

curl "https://api.wordlyenglish.com/v1/account?lang=tr" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Accept-Language: tr-TR"

Desteklenen dil kodları: en, tr, de, fr, es, it, pt, nl, pl, ru, uk, ar, fa, he, hi, bn, ur, zh, ja, ko, id, ms, vi, th, sv, no, da, fi, cs, ro.

Krediler ve faturalandırma

Each successful metered request consumes the documented number of credits. Email-verified accounts receive 50 free credits once. Credits are deducted atomically, so concurrent requests cannot spend the same balance twice. Balance lookup through GET /v1/account is free.

Use GET /v1/account when you need the current balance. Other endpoint responses include the operation charge but omit the remaining balance. When the balance is insufficient, the API returns HTTP 402 ve işlemi işlemez.

{
  "error": {
    "code": "credits_exhausted",
    "message": "Your credit balance is exhausted. Add a package or enable pay-as-you-go to continue.",
    "upgrade_url": "/app.php?page=billing"
  }
}

API anahtarının yaşam döngüsü

Geliştirme, hazırlama ve üretim için ayrı anahtarlar oluşturun. Wordly her anahtarın yalnızca kriptografik karmasını saklar; değerin tamamı oluşturma sırasında bir kez görüntülenir.

• Anahtarları ortama veya hizmete göre adlandırın.
• Ortam değişkenlerini veya yönetilen bir gizli depoyu kullanın.
• Açığa çıkmış olabilecek bir anahtarı derhal iptal edin.
• Eski değerleri tekrar kullanmadan tuşları döndürün.
• Anahtarları sorgu dizelerinde göndermeyin.

Yanıt formatı

Başarılı yanıtlar üst düzey bir data nesne ve şunları içerebilir: meta nesne. Hatalar her zaman üst düzey bir değer kullanır error makine tarafından okunabilen kararlı bir nesne code ve insan tarafından okunabilen message.

{
  "data": { ... },
  "meta": {
    "credits_used": 1,
    "request_id": "..."
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "..."
  }
}

Sakla request_id Başarılı bir faturalandırılmış istek hakkında destek ekibiyle iletişime geçtiğinizde. JSON, UTF-8 kodludur ve istemcilerin göndermesi gerekir Accept: application/json.

Üretim uç noktaları

Kelime uç noktaları

GET /v1/words/{word}

Tam bir kelime eşleşmesi döndürür. Kullanım languages=tr,de,fr yalnızca istenen çevirileri döndürmek için. Katalog veya çevrilmiş kayıtların maliyeti 1 kredidir; tamamen zenginleştirilmiş profillerin maliyeti 5 kredidir.

curl "https://api.wordlyenglish.com/v1/words/water?languages=tr,de" \
  -H "Authorization: Bearer $WORDLY_API_KEY"

GET /v1/words/search

Şu alanlarla arama yapın: q ve isteğe bağlı level, part_of_speech, category, limitve cursor. Limit 1 ile 50 arasındadır. Şunu gönderin: meta.next_cursor bir sonraki talebe.

curl "https://api.wordlyenglish.com/v1/words/search?q=app&level=advanced&limit=20" \
  -H "Authorization: Bearer $WORDLY_API_KEY"

GET /v1/words/random

1-20 rastgele kelimeyi döndürür. Şuna göre filtrele: level, part_of_speechveya category. Döndürülen her öğe bir kredi tutar.

POST /v1/words/batch

Tek bir istekte 1 ile 50 arasında benzersiz kelimeyi arar. Yanıt, istek sırasını korur ve her öğeyi şu şekilde işaretler: found.

curl -X POST "https://api.wordlyenglish.com/v1/words/batch?lang=tr" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"words":["water","opportunity"],"languages":["tr","de"]}'

GET /v1/languages

Desteklenen 30 arayüzün ve API mesajı yerel ayarının tamamını döndürür. Kelime çevirileri yalnızca mevcut olduğunda döndürülür. Bu uç nokta halka açıktır ve sıfır krediye mal olur.

Oran sınırı

Her API anahtarı, sürekli dakika başına 120 kabul edilen istekle sınırlıdır. Yanıtlar şunları içerir: X-RateLimit-Limit ve X-RateLimit-Remaining. bir 429 rate_limit_exceeded yanıt şunları içerir Retry-After: 60.

Response field reference

Every stable response variable is described below. Additive fields may appear later, so clients should ignore fields they do not recognize.

Vocabulary object

Meta object

Error object

Hatalar

Önerilen yeniden deneme politikası

Tekrar deneme 401, 402veya 404 otomatik olarak. Geçici için 5xx Yanıtlar için titreşimli üstel geri çekilme ve katı bir yeniden deneme sınırı kullanın. Kabul edilen her kimliği doğrulanmış istek kredi tüketebileceğinden asla sınırsız bir yeniden deneme döngüsü oluşturmayın.

JavaScript / Node.js

const response = await fetch('https://api.wordlyenglish.com/v1/account', {
  headers: {
    Authorization: `Bearer ${process.env.WORDLY_API_KEY}`,
    Accept: 'application/json'
  }
});

const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

console.log(body.data.credits_remaining);

Python

import os
import requests

response = requests.get(
    'https://api.wordlyenglish.com/v1/account',
    headers={
        'Authorization': f'Bearer {os.environ["WORDLY_API_KEY"]}',
        'Accept': 'application/json',
    },
    timeout=15,
)
response.raise_for_status()
print(response.json()['data']['credits_remaining'])

PHP

$curl = curl_init('https://api.wordlyenglish.com/v1/account');
curl_setopt_array($curl, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 15,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WORDLY_API_KEY'),
    'Accept: application/json',
  ],
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

if ($status >= 400) {
  throw new RuntimeException('Wordly API request failed');
}
$data = json_decode($body, true, flags: JSON_THROW_ON_ERROR);

Dart / Flutter

Wordly anahtarını Flutter uygulamasının içine göndermeyin. Örnek, güvenilir bir Dart arka ucuna veya sunucu işlevine aittir.

final response = await http.get(
  Uri.parse('https://api.wordlyenglish.com/v1/account'),
  headers: {
    'Authorization': 'Bearer ${Platform.environment['WORDLY_API_KEY']}',
    'Accept': 'application/json',
  },
);

final body = jsonDecode(response.body) as Map<String, dynamic>;
if (response.statusCode >= 400) {
  throw Exception((body['error'] as Map)['code']);
}

Üretim kontrol listesi

• Güvenilir bir arka uç aracılığıyla Proxy Wordly istekleri.
• Bağlantı ve yanıt zaman aşımlarını ayarlayın.
• Şu durumları 401, 402, 404ve 5xx ayrı ayrı ele alın.
• Query GET /v1/account when your application needs the current balance.
• Uç noktayı, durumu, gecikmeyi ve request_id API anahtarını kaydetmeden.
• Her ortam için ayrı anahtarlar kullanın ve bunları düzenli aralıklarla değiştirin.
• Cache stable vocabulary responses in your backend when appropriate.