Wordly API کے ساتھ بنائیں۔

کوئیک اسٹارٹ

ایک مفت اکاؤنٹ بنائیں، چھ ہندسوں کے کوڈ کا استعمال کرتے ہوئے اپنے ای میل کی تصدیق کریں، اور اپنے ڈویلپر ڈیش بورڈ میں ایک بار دکھائی جانے والی API کلید کو کاپی کریں۔

1. 1
   ایک اکاؤنٹ بنائیں

   صرف ایک ای میل ایڈریس اور پاس ورڈ کے ساتھ رجسٹر کریں۔

2. 2
   اپنے ای میل کی تصدیق کریں۔

   کی طرف سے بھیجا گیا کوڈ درج کریں۔ [email protected]. Verification grants 50 free credits.

3. 3
   اپنی API کلید کو اسٹور کریں۔

   تیار کردہ کاپی کریں۔ wly_live_... کلید بنائیں اور اسے سرور سائیڈ ماحول کے متغیر میں رکھیں۔

4. 4
   ٹیسٹ کی درخواست کریں۔

   تصدیق کی توثیق کرنے اور بقیہ بیلنس دیکھنے کے لیے اکاؤنٹ اینڈ پوائنٹ پر کال کریں۔

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" }
}

بیس یو آر ایل اور ورژننگ

تمام پروڈکشن اینڈ پوائنٹس درج ذیل ورژن والے بیس یو آر ایل سے پیش کیے جاتے ہیں:

بریکنگ رسپانس یا رویے میں تبدیلیاں ایک نیا پاتھ ورژن استعمال کریں گی۔ اضافی فیلڈز کے اندر متعارف کرایا جا سکتا ہے v1, so clients should ignore response properties they do not recognize.

تصدیق

توثیق شدہ اختتامی پوائنٹس کو HTTP میں API کلید کی ضرورت ہوتی ہے۔ Authorization بیئرر اسکیم کا استعمال کرتے ہوئے ہیڈر۔

Authorization: Bearer wly_live_your_api_key

مقامی API پیغامات

کے ساتھ جوابی زبان سیٹ کریں۔ ?lang=tr یا معیار Accept-Language ہیڈر استفسار کے پیرامیٹرز کو فوقیت حاصل ہے۔ ہر JSON جواب میں منتخب کردہ مقام کا اعلان کرتا ہے۔ Content-Language اور meta.lang. Error codes remain stable in English for programmatic handling; only the human-readable message is localized.

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

معاون زبان کے کوڈز: 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.

کریڈٹ اور بلنگ

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 اور آپریشن پر کارروائی نہیں کرتا۔

{
  "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 key lifecycle

ڈویلپمنٹ، سٹیجنگ اور پروڈکشن کے لیے علیحدہ کلیدیں بنائیں۔ Wordly ہر کلید کی صرف ایک کرپٹوگرافک ہیش اسٹور کرتا ہے۔ مکمل قدر تخلیق کے وقت ایک بار ظاہر ہوتی ہے۔

• ماحول یا خدمت کے لحاظ سے نام کی چابیاں۔
• ماحولیاتی متغیرات یا منظم خفیہ اسٹور کا استعمال کریں۔
• اگر کسی کلید کو ظاہر کیا گیا ہو تو اسے فوری طور پر منسوخ کریں۔
• پرانی اقدار کو دوبارہ استعمال کیے بغیر چابیاں گھمائیں۔
• استفسار کے تاروں میں چابیاں نہ بھیجیں۔

جوابی شکل

کامیاب جوابات اعلیٰ سطح کا استعمال کرتے ہیں۔ data اعتراض اور شامل ہوسکتا ہے a meta اعتراض غلطیاں ہمیشہ اعلیٰ سطح کا استعمال کرتی ہیں۔ error ایک مستحکم مشین کے ساتھ پڑھنے کے قابل آبجیکٹ code اور انسانی پڑھنے کے قابل message.

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

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

رکھیں request_id کامیاب بل کی درخواست کے بارے میں سپورٹ سے رابطہ کرتے وقت۔ JSON UTF-8 انکوڈ شدہ ہے اور کلائنٹس کو بھیجنا چاہیے۔ Accept: application/json.

پیداوار کے اختتامی مقامات

الفاظ کے اختتامی نکات

GET /v1/words/{word}

ایک عین مطابق الفاظ کی مماثلت لوٹاتا ہے۔ استعمال کریں۔ languages=tr,de,fr صرف درخواست کردہ ترجمے واپس کرنے کے لیے۔ کیٹلاگ یا ترجمہ شدہ ریکارڈز کی قیمت 1 کریڈٹ؛ مکمل طور پر افزودہ پروفائلز کی قیمت 5 کریڈٹس۔

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

GET /v1/words/search

کے ساتھ تلاش کریں۔ q اور اختیاری level, part_of_speech, category, limit, and cursor. Limits range from 1 to 50. Pass meta.next_cursor اگلی درخواست میں۔

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 بے ترتیب الفاظ لوٹاتا ہے۔ کے لحاظ سے فلٹر کریں۔ level, part_of_speech, or category. Each returned slot costs one credit.

POST /v1/words/batch

ایک درخواست میں 1 اور 50 کے درمیان منفرد الفاظ نظر آتے ہیں۔ جواب درخواست کے آرڈر کو محفوظ رکھتا ہے اور ہر آئٹم کو نشان زد کرتا ہے۔ 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

تمام 30 تعاون یافتہ انٹرفیس اور API- میسج لوکلز لوٹاتا ہے۔ الفاظ کے ترجمے صرف دستیاب ہونے پر واپس کیے جاتے ہیں۔ یہ اختتامی نقطہ عوامی ہے اور اس کی قیمت صفر کریڈٹ ہے۔

شرح کی حد

ہر API کلید فی رولنگ منٹ 120 قبول شدہ درخواستوں تک محدود ہے۔ جوابات شامل ہیں۔ X-RateLimit-Limit اور X-RateLimit-Remaining. A 429 rate_limit_exceeded جواب شامل ہے 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

غلطیاں

دوبارہ کوشش کرنے کی تجویز کردہ پالیسی

دوبارہ کوشش نہ کریں۔ 401, 402, or 404 خود بخود عارضی کے لیے 5xx جوابات، jitter اور ایک سخت دوبارہ کوشش کیپ کے ساتھ ایکسپونینشل بیک آف کا استعمال کریں۔ کبھی بھی بغیر کسی حد کے دوبارہ کوشش کرنے کا لوپ نہ بنائیں کیونکہ ہر منظور شدہ تصدیق شدہ درخواست کریڈٹ استعمال کر سکتی ہے۔

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);

ازگر

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'])

پی ایچ پی

$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);

ڈارٹ / پھڑپھڑانا

فلٹر ایپلیکیشن کے اندر Wordly کلید نہ بھیجیں۔ مثال ایک بھروسہ مند ڈارٹ بیک اینڈ یا سرور فنکشن سے تعلق رکھتی ہے۔

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']);
}

پروڈکشن چیک لسٹ

• پراکسی ورڈلی ایک بھروسہ مند بیک اینڈ کے ذریعے درخواست کرتا ہے۔
• کنکشن اور رسپانس ٹائم آؤٹ سیٹ کریں۔
• سنبھالنا 401, 402, 404, and 5xx الگ سے
• Query GET /v1/account when your application needs the current balance.
• لاگ اینڈ پوائنٹ، اسٹیٹس، لیٹینسی، اور request_id API کلید کو لاگ ان کیے بغیر۔
• ماحول کے مطابق الگ الگ کلیدیں استعمال کریں اور انہیں وقفے وقفے سے گھمائیں۔
• Cache stable vocabulary responses in your backend when appropriate.