• مدیر سایت
• آگوست 11, 2019

مستندات 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 پاسخ، یکی از کدهای زیر بازگشت داده می‌شود.

دیتابیس‌ها
دیتابیس‌های موجود در واژه‌یاب به شرح زیر است.

جست‌وجوی واژه        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=آسمان

در این مطلب در مورد مستندات وب سرویس واژه یاب صحبت کردیم در مطلب بعدی نمونه کدهای این  وب سرویس را بررسی میکنیم

منبع

• برچسب ها:
• api فرهنگ لغت
• api واژه یاب
• راهنمای api لغت
• راهنمای وب سرویس لغت
• وب سرویس فرهنگ لغت
• وب سرویس واژه یاب