API واژه‌ها

کلید شما

کلید را در هدر Authorization به‌صورت bearer بفرستید، یا در هدر X-API-Key.

سطح رایگان

با کلید رایگان می‌توانید روزی ۱۰ درخواست بفرستید. شمارش ساعت 00:00 به وقت UTC دوباره شروع می‌شود. هر درخواست به یک نقطهٔ دادهٔ API یک درخواست حساب می‌شود. هدرهای X-RateLimit-Limit و X-RateLimit-Remaining و X-RateLimit-Reset نشان می‌دهند چقدر باقی مانده است.

نقاط دسترسی

همهٔ مسیرها با /api/v1 شروع می‌شوند. شرح کامل در فایل OpenAPI است.

• GET /api/v1/words واژه‌هایی که با فیلترها می‌خوانند
• GET /api/v1/words/{word} همهٔ مدخل‌ها با این املا
• GET /api/v1/themes موضوع‌های دارای واژه، با تعداد و نام
• GET /api/v1/themes/{theme}/words واژه‌های یک موضوع
• GET /api/v1/levels سطح‌های CEFR دارای واژه، با تعداد
• GET /api/v1/levels/{level}/words واژه‌های یک سطح
• GET /api/v1/word-of-the-day واژهٔ امروز (UTC)
• GET /api/v1/word-of-the-day/{date} واژهٔ یک روز، سال-ماه-روز (YYYY-MM-DD)
• GET /api/v1/random واژه‌های تصادفی، هرگز از حافظهٔ نهان
• GET /api/v1/export/words.json همهٔ واژه‌های نمایان به‌صورت JSON
• GET /api/v1/export/words.csv همهٔ واژه‌های نمایان به‌صورت CSV
• GET /api/v1/meta نسخهٔ داده، تعداد‌ها، وضعیت‌های بازبینیِ نمایان، پروانه‌ها. باز است و کلید نمی‌خواهد. (بدون نیاز به کلید)

شرح OpenAPI (JSON)

فیلد review_status

هر مقدار یک review_status دارد که نشان می‌دهد تا کجا بررسی شده است: owner (واردشده یا تأییدشده توسط مالک)، reviewed، imported (برگرفته از یک منبع آزاد)، machine (پیش‌نویس ماشینی که هنوز انسانی آن را بررسی نکرده) و draft. نقطهٔ /meta فهرست وضعیت‌هایی را که API اکنون می‌فرستد نشان می‌دهد. اگر فقط داده‌های بررسی‌شده می‌خواهید، این فیلد را بررسی کنید.

خطاها

همهٔ خطاها یک شکل دارند: یک شیء error با status و code و message.

• bad_request: 400: یکی از پارامترها درست نیست. پیام آن را نام می‌برد.
• unauthorized: 401: کلید نیست، شناخته‌شده نیست یا باطل شده است.
• forbidden: 403: این کلید این نقطه‌ی پایانی را پوشش نمی‌دهد.
• not_found: 404: چیزی پیدا نشد.
• rate_limited: 429: کلید درخواست‌های امروز را مصرف کرده است. هدر Retry-After ثانیه‌های مانده تا 00:00 به وقت UTC را می‌دهد.
• server_error: 500: از سمت ما مشکلی پیش آمد. بعداً دوباره امتحان کنید.

نمونه

همین درخواست با curl، جاوااسکریپت و پایتون. به‌جای YOUR_KEY کلید خودتان را بگذارید و هرگز آن را در کد عمومی قرار ندهید.

curl -H "Authorization: Bearer ih_live_YOUR_KEY" \
  "https://inburgering.help/api/v1/words/fiets?lang=en,fa"

const response = await fetch("https://inburgering.help/api/v1/words/fiets?lang=en,fa", {
  headers: { Authorization: "Bearer ih_live_YOUR_KEY" },
});
if (response.status === 429) {
  // Over the limit: try again after this many seconds.
  console.log("Retry after", response.headers.get("Retry-After"));
} else if (!response.ok) {
  console.log((await response.json()).error.message);
} else {
  console.log(await response.json());
}

import requests

response = requests.get(
    "https://inburgering.help/api/v1/words/fiets?lang=en,fa",
    headers={"Authorization": "Bearer ih_live_YOUR_KEY"},
    timeout=10,
)
if response.status_code == 429:
    # Over the limit: try again after this many seconds.
    print("Retry after", response.headers["Retry-After"])
else:
    response.raise_for_status()
    print(response.json())

نسخه‌ها و تغییرها

رابط برنامه‌نویسی اکنون نسخهٔ ۱ است (/api/v1). در یک نسخه فقط فیلد و نقطهٔ پایانی اضافه می‌شود؛ پس فیلدهایی را که نمی‌شناسید نادیده بگیرید. تغییری که ممکن است کلاینت را از کار بیندازد نسخهٔ تازه می‌گیرد و نسخهٔ قدیمی پیش از خاموش شدن برای مدتی اعلام‌شده در دسترس می‌ماند. تغییرها در ادامه آمده‌اند.

• v1
  • نسخهٔ نخست: واژه‌ها، موضوع‌ها، سطح‌ها، واژهٔ روز، واژه‌های تصادفی، خروجی گرفتن و meta.
  • کلید با محدودیت روزانه برای هر سطح؛ در صورت نیاز محدودیت ماهانه، وضعیت بازبینی و دسترسی (خواندن، خروجی) برای هر سطح.
  • نام موضوع‌ها به هلندی و انگلیسی؛ نام فارسی، عربی و ترکی موضوع‌ها پیش‌نویس است (پاسخ themes آن‌ها را در labels_draft می‌آورد).

درخواست کلید API

فعلاً به درخواست‌کنندگان تازه کلید داده نمی‌شود. بعداً دوباره سر بزنید.