مستندات API واژه یاب
در مقاله قبل در مورد توضیحات وب سرویس واژه یاب صحبت کردیم اما در این مقاله در مورد مستندات وب سرویس واژه یاب صحبت خواهیم کرد
پیش از شروع، پیش‌نیازهایی برای ارتباط با سرور وجود دارد. قبل از هر کاری توسعه‌دهنده موظف است در واژه‌یاب عضو شود و از طریق پنل کاربری اقدام به دریافت توکن نماید. توکن، یک رشتهٔ منحصر به فرد است که به توسعه‌دهنده اختصاص داده می‌شود و از این طریق احراز هویت او در هر بار ارتباط با سرور انجام می‌گردد. این رشته، محرمانه بوده و توسعه‌دهنده باید برای تأمین امنیت اشتراک خود در حفظ آن کوشا باشد. بدیهی است امکان تولید دوبارهٔ توکن از طریق پنل کاربری فراهم خواهد بود.
ساختار URL
ساختار URL برای ارتباط به سرور به‌طور کلی به شکل زیر است.
http://api.vajehyab.com/v3/[method_name]?[[parameter]=[value]]&[[parameter]=[value]]&…
پارامترها
سرور از REST پشتیبانی می‌کند و پارامترهای ورودی بصورت Query String و پاسخ خروجی، json می‌باشد. همچنین در هر درخواست، علاوه‌بر پارامترهای مختص آن متد، لازم است پارامترهای زیر نیز وجود داشته باشند:
- token رشته‌ای است که برای احراز هویت توسعه‌دهنده استفاده می‌شود.
- ip برای پیگیری‌های آتی، بهتر است تا آدرس IP کاربران سرویس خود در این پارامتر درج شود. این پارامتر اختیاری است.
- product نام محصولی که از api استفاده می‌کند در این پارامتر درج می‌شود. در این صورت می‌توان در آینده آماری از درخواست‌ها بر اساس نام محصول در اختیار داشت.
- prettyprint با true کردن این پارامتر، پاسخ خروجی، اصطلاحاً pretty printed خواهد بود. این مقدار بصورت پیشفرض true است.
- debug با true بودن این پارامتر، اطلاعاتی برای debug در اختیار توسعه‌دهنده قرار خواهد گرفت.
کدهای پاسخ
در Header پاسخ، یکی از کدهای زیر بازگشت داده می‌شود.
| کد | توضیحات |
|---|---|
| ۲۰۰ | سرور با موفقیت واژه را جست‌وجو کرده است. |
| ۴۰۰ | سرور قادر به تشخیص پارامترهای ورودی نیست. پارامترهای اجباری یافت نشده‌اند. |
| ۴۰۱ | توسعه‌دهنده توسط سرور قادر به شناسایی نیست. |
| ۴۰۳ | سرور بنا به دلایل مشخص مانع دسترسی توسعه‌دهنده شده است. |
| ۴۰۴ | عبارت درخواست شده یافت نشد. |
| ۴۰۵ | متد مجاز نیست. |
| ۵۰۰ | سرور با خطا مواجه شده و قادر به انجام درخواست نمی‌باشد. |
| ۵۰۳ | سرور در حال حاضر در دسترس نمی‌باشد. |
دیتابیس‌ها
دیتابیس‌های موجود در واژه‌یاب به شرح زیر است.
| نام | توضیحات |
|---|---|
| dehkhoda | لغت‌نامهٔ دهخدا |
| moein | فرهنگ فارسی معین |
| amid | فرهنگ فارسی عمید |
| motaradef | واژگان مترادف و متضاد |
| farhangestan | فرهنگ واژه‌های مصوّب فرهنگستان |
| sareh | واژه‌های فارسی سره |
| ganjvajeh | فرهنگ گنجواژه |
| wiki | واژه‌نامهٔ آزاد |
| slang | اصطلاحات عامیانه |
| quran | فرهنگ واژگان قرآن |
| name | فرهنگ نام‌ها |
| thesis | فرهنگ لغات علمی |
| isfahani | لهجه و گویش اصفهانی |
| bakhtiari | لهجه و گویش بختیاری |
| tehrani | لهجه و گویش تهرانی |
| dezfuli | لهجه و گویش دزفولی |
| gonabadi | لهجه و گویش گنابادی |
| mazani | لهجه و گویش مازنی |
| en2fa | دیکشنری انگلیسی به فارسی |
| ar2fa | دیکشنری عربی به فارسی |
| fa2en | دیکشنری فارسی به انگلیسی |
| fa2ar | دیکشنری فارسی به عربی |
جست‌وجوی واژه search
برای جست‌وجوی یک واژه و یا عبارت از این متد استفاده می‌شود. معنی واژه محدود شده و در انتهای آن «…» درج می‌شود.
پارامترها
- q واژه و یا عبارتی است که می‌خواهید جست‌وجو کنید.
- type نوع جست‌وجو را مشخص می‌کند. مقدار exact برای جست‌وجوی دقیق، ava برای جست‌وجوی هم‌آوا، like برای جست‌وجوی مشابه و text برای جست‌وجو در معنی واژه استفاده می‌شود.
- start مشخص می‌کند که از چه ردیفی جست‌وجو آغاز گردد. این پارامتر بصورت پیشفرض ۰ است.
- rows تعداد ردیف‌ها برای جست‌وجو. این پارامتر بصورت پیشفرض ۱۰ است و حداکثر مقدار آن ۵۰ می‌باشد.
- filter مشخص می‌کند که جست‌وجو در چه لغت‌نامه‌هایی و با چه اولویتی انجام شود.
پاسخ
GET /search? HTTP/1.1
Host: vajehyab.com
Content-Type: application/json; charset=utf-8
Content-Length: 137
{
response: {
status: true,
code: 200
},
meta: {
q: “آسمان”,
type: “exact”,
start: “0”
},
data: {
num_found: 13,
results: [
{
id: “dehkhoda_33791”,
title: “اسمان”,
text: “اسمان . [ اَ ] (اِ)صورتی است از آسمان که فلک باشد. || نام روز بیست وهفتم از هر ماه شمسی . (ناظم الاطباء). روز بیست وپنجم است از ماههای قدیم و بیست وهفتم نیز به نظرآمده است . (برهان ) (آنندراج ). رجوع به آسمان شود.”,
source: “لغت‌نامه دهخدا”,
db: “dehkhoda”,
num: 1
},
{
id: “dehkhoda_1530”,
title: “آسمان”,
text: “آسمان . [ س ْ / س ِ ] (اِ) چرخ . سماء. سما. فلک . اثیر. ام النجوم . سپهر. گنبد. گردون . گرزمان . خضراء. خضرا. میناء. عجوز. جرباء. رقیع. ضاحیه . جربهالنجوم . و آن بعقیده ٔ قدماء هفت باشد. مقابل زمین : اخترانند آسمانْشان جایگاه هفت تابنده دوان در دو و …”,
source: “لغت‌نامه دهخدا”,
db: “dehkhoda”,
num: 1
},
{
id: “fa2ar_2605”,
title: “اسمان”,
text: “ارتفاع , سماء , غرفه علویه”,
source: “دیکشنری فارسی به عربی”,
db: “fa2ar”,
num: 1
},
{
id: “mazani_272”,
title: “آسمان”,
text: “آسمان”,
source: “لهجه و گویش مازنی”,
db: “mazani”,
num: 1
}
]
}
}
چند مثال
http://api.vajehyab.com/v3/search?token=YOUR_TOKEN&q=سلام&type=exact&filter=dehkhoda,moein
http://api.vajehyab.com/v3/search?token=YOUR_TOKEN&q=نگرش&type=like&row=5&start=10
http://api.vajehyab.com/v3/search?token=YOUR_TOKEN&q=آسمان+آبی&type=text
دریافت معنی واژه word
برای دریافت معنی کامل یک واژه از این متد استفاده می‌شود. این امکان وجود دارد که در معنی واژه کدهای HTML وجود داشته باشد.
پارامترها
- title واژه‌ای که از متد search استخراج شده‌است.
- db نام دیتابیس که از متد search استخراج شده‌است.
- num پارامتر num که از متد search استخراج شده‌است.
پاسخ
GET /word? HTTP/1.1
Host: vajehyab.com
Content-Type: application/json; charset=utf-8
Content-Length: 137
{
response: {
status: true,
code: 200
},
meta: {
word: “آسمان”,
num: “1”,
db: “amid”
},
word: {
id: “amid_538”,
title: “آسمان”,
title_en: “”,
pron: “/’ās[e]mān/”,
db: “amid”,
source: “فرهنگ فارسی عمید”,
text: “۱. (نجوم) فضای بی‌پایان و نیلگون که بالای سر ما دیده می‌شود. رنگ آبی آن، رنگ هوایی است که کرۀ زمین را احاطه کرده است.
۲. (نجوم) فضایی که ستارگان و کهکشان‌ها در آن قرار دارند.
۳. سقف بنا.
۴. نیروهایی ماوراءالطبیعه که بر سرنوشت انسان تاثیر می‌گذارند؛ سپهر؛ گردون؛ فلک.
۵. [قدیمی] روز بیست‌وهفتم از هر ماه اوستایی:◻︎ آسمان‌روز ای چو ماه آسمان / باده نوش و دار دل را شادمان (مسعودسعد: ۵۵۰).”
}
}
چند مثال
http://api.vajehyab.com/v3/word?token=YOUR_TOKEN&title=سلام&db=dehkhoda&num=1
http://api.vajehyab.com/v3/word?token=YOUR_TOKEN&title=سلام&db=dehkhoda&num=2
پیشنهاد واژه suggest
لیست پیشنهادی برای استفاده در auto complete از این متد دریافت می‌شود.
پارامترها
- q واژه و یا یک عبارت
پاسخ
GET /suggest? HTTP/1.1
Host: vajehyab.com
Content-Type: application/json; charset=utf-8
Content-Length: 137
{
response: {
status: true,
code: 200
},
meta: {
q: “آسم”
},
data: {
suggestion: [
“چراغ آسمان”,
“چراغ آسمانی”,
“چم آسمان”,
“تعویذ آسمان”,
“حجر آسمان جونی”,
“آتش آسمان”,
“آسمار”
]
}
}
چند مثال
http://api.vajehyab.com/v3/suggest?token=YOUR_TOKEN&q=آسما
http://api.vajehyab.com/v3/suggest?token=YOUR_TOKEN&q=آسمان
در این مطلب در مورد مستندات وب سرویس واژه یاب صحبت کردیم در مطلب بعدی نمونه کدهای این وب سرویس را بررسی میکنیم