رہنمائے میڈیاویکی اےپی‌آئی

ذیل میں میڈیاویکی اےپی‌آئی کی دستاویزی تفصیلات درج ہیں جو خودکار طور پر لکھی گئی ہیں۔

دستاویز اور مثالوں کے لیے ملاحظہ فرمائیں: https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page

اصل ماڈیول

ماخذ: MediaWiki
اجازت نامہ: GPL-2.0-or-later

کیفیت: میڈیاویکی اےپی‌آئی ایک مکمل اور مستحکم انٹرفیس ہے جس میں اصلاح و تحسین کا عمل مستقل جاری رہتا ہے۔ گو کہ ہم ایسی کسی تبدیلی سے گریز کرتے ہیں جس سے سارا نظام شکستہ اور ٹوٹ پھوٹ کا شکار ہو جائے لیکن بعض اوقات اس کے بغیر چارہ نہیں ہوتا؛ چنانچہ ان تبدیلیوں کی بروقت اطلاع پانے کے لیے the mediawiki-api-announce اس فہرست میں اپنا نام درج کر دیں۔

غلط درخواستیں: جب اےپی‌آئی کو غلط درخواستیں بھیجی جاتی ہیں تو «MediaWiki-API-Error» کی کلید کے ساتھ ایک ایچ‌ٹی‌ٹی‌پی سرنامہ روانہ کیا جاتا ہے، اور بعد ازاں ان دونوں کو یعنی سرنامہ کی قدر اور نقص کوڈ کو یکساں قدر دے دی جاتی ہے۔ مزید معلومات کے لیے API: Errors and warnings ملاحظہ فرمائیں۔

جانچ: اےپی‌آئی درخواستوں کی جانچ کے لیے Special:ApiSandbox ملاحظہ کریں۔

مخصوص پیرامیٹر:

action

جونسا کام مطلوب ہو۔

block: صارف پر پابندی عائد کرتا ہے۔
changeauthenticationdata: موجودہ صارف کی تصدیق و توثیق کی تفصیلات میں تبدیلی کرتا ہے۔
changecontentmodel: مندرجات صفحہ کا طرز تبدیل کرتا ہے
checktoken: action=query&meta=tokens کے ٹوکن کی صحت کی جانچ کرتا ہے۔
clearhasmsg: موجودہ صارف کے hasmsg پرچم کو صاف کرتا ہے۔
clientlogin: متعامل فلو کی مدد سے ویکی میں داخل ہوتا ہے۔
compare: دو صفحات کے درمیان فرق اخذ کرتا ہے۔
createaccount: نیا صارف کھاتہ بناتا ہے۔
delete: صفحہ حذف کرتا ہے۔
edit: صفحات کو تخلیق یا ان میں ترمیم کرتا ہے۔
emailuser: صارف کو برقی ڈاک بھیجتا ہے۔
expandtemplates: ویکی متن میں موجود تمام سانچوں کو کھولتا ہے۔
feedcontributions: جواب میں صارف کی شراکتوں کی فیڈ بھیجتا ہے۔
feedrecentchanges: جواب میں حالیہ تبدیلیوں کی فیڈ بھیجتا ہے۔
feedwatchlist: جواب میں زیر نظر فہرست کی فیڈ بھیجتا ہے۔
filerevert: فائل کو پرانے نسخے کی جانب لوٹاتا ہے۔
help: مخصوص ماڈیول کے معاون صفحات دکھاتا ہے۔
imagerotate: Rotate one or more images.
import: کسی دوسری ویکی سے یا XML فائل سے صفحہ درآمد کرتا ہے۔
linkaccount: Link an account from a third-party provider to the current user.
login: لاگ ان ہو کر توثیقی کوکیز حاصل کرتا ہے۔
logout: لاگ آؤٹ ہو کر نشست کے سارے ڈیٹا کو صاف کرتا ہے۔
managetags: ٹیگوں کی تبدیلی سے متعلق انتظامی امور انجام دیتا ہے۔
mergehistory: صفحہ کے تاریخچوں کو ضم کرتا ہے۔
mlm-tasks: Manage translation tasks
move: صفحہ منتقل کرتا ہے۔
opensearch: اوپن سرچ پروٹوکول کا استعمال کرتے ہوئے ویکی ویب گاہ میں تلاش کرتا ہے۔
options: موجودہ صارف کی ترجیحات تبدیل کرتا ہے۔
paraminfo: متعدد اےپی آئی ماڈیول کے بارے میں معلومات حاصل کرتا ہے۔
parse: مندرجات کا تجزیہ کرکے نتائج واپس بھیجتا ہے۔
patrol: صفحہ یا صفحہ کے نسخہ کی مراجعت کرتا ہے۔
pfautocomplete: Autocompletion used by the Page Forms extension.
pfautoedit: Create or edit a page using a form defined by the Page Forms extension.
protect: صفحہ کے درجۂ حفاظت کو تبدیل کرتا ہے۔
purge: دیے گئے عناوین کے کیش صاف کرتا ہے۔
query: میڈیاویکی سے اور میڈیاویکی کے متعلق معلومات اخذ کرتا ہے۔
removeauthenticationdata: موجودہ صارف کی تصدیق و توثیق کی تفصیلات کو حذف کرتا ہے۔
resetpassword: صارف کو پاس ورڈ دوبارہ مرتب کرنے کے لیے برقی ڈاک بھیجتا ہے۔
revisiondelete: نسخوں کو حذف یا بحال کرتا ہے۔
rollback: صفحہ کی آخری ترمیم کو رد کرتا ہے۔
rsd: RSD خاکہ کو برآمد کرتا ہے۔
setnotificationtimestamp: Update the notification timestamp for watched pages.
setpagelanguage: Change the language of a page.
tag: Add or remove change tags from individual revisions or log entries.
unblock: Unblock a user.
undelete: Undelete revisions of a deleted page.
unlinkaccount: Remove a linked third-party account from the current user.
upload: Upload a file, or get the status of pending uploads.
userrights: Change a user's group membership.
validatepassword: Validate a password against the wiki's password policies.
watch: Add or remove pages from the current user's watchlist.
cspreport: داخلی۔ Used by browsers to report violations of the Content Security Policy. This module should never be used, except when used automatically by a CSP compliant web browser.
stashedit: داخلی۔ Prepare an edit in shared cache.
visualeditor: داخلی۔ Returns HTML5 for a page from the Parsoid service.
visualeditoredit: داخلی۔ Save an HTML5 page to MediaWiki (converted to wikitext via the Parsoid service).

ذیل کی قدروں میں سے کوئی ایک: block، changeauthenticationdata، changecontentmodel، checktoken، clearhasmsg، clientlogin، compare، createaccount، delete، edit، emailuser، expandtemplates، feedcontributions، feedrecentchanges، feedwatchlist، filerevert، help، imagerotate، import، linkaccount، login، logout، managetags، mergehistory، mlm-tasks، move، opensearch، options، paraminfo، parse، patrol، pfautocomplete، pfautoedit، protect، purge، query، removeauthenticationdata، resetpassword، revisiondelete، rollback، rsd، setnotificationtimestamp، setpagelanguage، tag، unblock، undelete، unlinkaccount، upload، userrights، validatepassword، watch، cspreport، stashedit، visualeditor، visualeditoredit

طے شدہ: help

format

حاصل شدہ مواد کا فارمیٹ۔

json: ڈیٹا کو JSON شکل میں دیتا ہے۔
jsonfm: ڈیٹا کو JSON شکل میں دیتا ہے (ایچ ٹی ایم ایل کے خوب صورت انداز میں)
none: کوئی معلومات نہیں دیتا۔
php: ڈیٹا کو سیریلائزڈ پی ایچ پی فارمیٹ میں دیتا ہے۔
phpfm: ڈیٹا کو سیریلائزڈ پی ایچ پی فارمیٹ میں دیتا ہے (ایچ ٹی ایم ایل کے خوب صورت انداز میں)۔
rawfm: ڈیٹا کو JSON شکل میں دیتا ہے جس میں غلطیوں کی اصلاح کے عناصر بھی شامل ہوتے ہیں (ایچ ٹی ایم ایل کے خوب صورت انداز میں)۔
xml: ڈیٹا کو XML شکل میں دیتا ہے۔
xmlfm: ڈیٹا کو XML شکل میں دیتا ہے (ایچ ٹی ایم ایل کے خوب صورت انداز میں)۔

ذیل کی قدروں میں سے کوئی ایک: json، jsonfm، none، php، phpfm، rawfm، xml، xmlfm

طے شدہ: jsonfm

maxlag

جب ڈیٹابیس ریپلی کیٹڈ سروَر پر میڈیاویکی نصب ہو تو بغایت تاخیر (Maximum lag) کو استعمال کیا جا سکتا ہے۔ سائٹ ریپلی کیشن میں مزید تاخیر کا سبب بننے والے اقدامات کو محفوظ کرنے کے لیے یہ پیرامیٹر کلائنٹ کو تب تک منتظر رکھ سکتا ہے جب تک ریپلی کیشن کی تاخیر متعینہ قدر سے کم ہو۔ حد سے زیادہ تاخیر کی صورت میں maxlag کا نقص Waiting for $host: $lag seconds lagged جیسے پیغام کے ساتھ نظر آئے گا۔
مزید تفصیلات کے لیے Manual: Maxlag parameter سے رجوع کریں۔

Type: integer

smaxage

s-maxage کے ایچ ٹی ٹی پی کیش کنٹرول سرنامہ کو سیکنڈ کی اس تعداد پر رکھیں۔ غلطیاں کبھی محفوظ نہیں ہوتیں۔

Type: integer

طے شدہ: 0

maxage

max-age کے ایچ ٹی ٹی پی کیش کنٹرول سرنامہ کو سیکنڈ کی اس تعداد پر رکھیں۔ غلطیاں کبھی محفوظ نہیں ہوتیں۔

Type: integer

طے شدہ: 0

assert

Verify that the user is logged in if set to user, not logged in if set to anon, or has the bot user right if bot.

ذیل کی قدروں میں سے کوئی ایک: anon، bot، user

assertuser

تصدیق کرتا ہے کہ موجودہ صارف ہی وہ صارف ہے جس کا نام درج کیا گیا ہے۔

طرز: صارف، بذریعہ صارف نام

requestid

یہاں دی گئی کوئی بھی قدر جواب میں شامل کی جائے گی۔ درخواستوں میں فرق کرنے کے لیے اسے استعمال کیا جا سکتا ہے۔

servedby

نتائج میں اس ہوسٹ کا نام شامل کرتا ہے جس نے درخواست کی تکمیل کی۔

طرز: بولین (تفصیلات)

curtimestamp

نتیجہ میں وقت و تاریخ کی موجودہ مہر شامل کرتا ہے۔

طرز: بولین (تفصیلات)

responselanginfo

نتیجہ میں uselang اور errorlang کے لیے استعمال ہونے والی زبانیں شامل کرتا ہے۔

طرز: بولین (تفصیلات)

origin

کراس ڈومین اجیکس رکویسٹ (CORS) کی مدد سے اےپی‌آئی تک پہنچنا ہو تو اس پیرامیٹر میں اصل ڈومین فراہم کریں۔ کسی بھی pre-flight درخواست میں اس کی شمولیت لازمی ہے اور اسی بنا پر اسے یوآرآئی درخواست کا جز ہونا چاہیے (POST کا نہیں)۔

جہاں تک تصدیق شدہ درخواستوں کا معاملہ ہے، ان میں بھی Origin سرنامہ میں موجود مصادر میں سے کسی ایک کے مطابق اس پیرامیٹر کا ہونا لازمی ہے۔ لہذا اسے کچھ یوں https://ur.wikipedia.org یا https://meta.wikimedia.org رکھیں۔ اگر یہ پیرامیٹر Origin سرنامہ کے مماثل ہے اور مصدر کو اجازت حاصل ہے تو Access-Control-Allow-Origin اور Access-Control-Allow-Credentials کے سرنامے مرتب کر دیے جائیں گے۔

اس کے برعکس غیر تصدیق شدہ درخواستوں میں * کی قدر درج کریں۔ یہ Access-Control-Allow-Origin سرنامہ کو ترتیب دے گا اور Access-Control-Allow-Credentials کا سرنامہ بھی false ہوگا، نیز صارف سے متعلق تمام معلومات محدود کر لی جائیں گی۔

uselang

Language to use for message translations. action=query&meta=siteinfo&siprop=languages returns a list of language codes, or specify user to use the current user's language preference, or specify content to use this wiki's content language.

طے شدہ: user

variant

زبان کی کوئی بولی۔ صرف اس صورت میں کام کرتا ہے جب اصل زبان کی مختلف بولیاں موجود ہوں۔

errorformat

نقص اور انتباہ کی عبارتوں کے لیے استعمال ہونے والا فارمیٹ

plaintext: ویکی متن جس میں ایچ ٹی ایم ایل کے ٹیگ کو حذف اور موجودات کو بدل دیا جاتا ہے۔
wikitext: غیر تجزیہ شدہ ویکی متن۔
html: HTML
raw: پیغام کی کلید اور پیرامیٹر۔
none: کوئی عبارت نہیں، فقط نقائص کے کوڈ۔
bc: میڈیاویکی کے نسخہ 1.29 سے قبل استعمال ہونے والا فارمیٹ۔ errorlang اور errorsuselocal کو نظر انداز کر دیا جاتا ہے۔

ذیل کی قدروں میں سے کوئی ایک: bc، html، none، plaintext، raw، wikitext

طے شدہ: bc

errorlang

Language to use for warnings and errors. action=query&meta=siteinfo&siprop=languages returns a list of language codes, or specify content to use this wiki's content language, or specify uselang to use the same value as the uselang parameter.

طے شدہ: uselang

errorsuselocal

اسے درج کرنے کی صورت میں نقص کی عبارتیں میڈیاویکی نام فضا میں موجود مقامی زبانوں میں نظر آئیں گی۔

طرز: بولین (تفصیلات)

مثالیں

اصل ماڈیول کی رہنما تفصیلات۔: api.php?action=help [تختۂ مشق میں کھولیں]
ایک صفحہ میں تمام رہنمائیاں۔: api.php?action=help&recursivesubmodules=1 [تختۂ مشق میں کھولیں]

اجازت:

writeapi: اے پی آئی تحریر کا استعمال; معطیٰ لہ: all، user اور bot
apihighlimits: اےپی آئی استفسارات میں اعلیٰ حدود کا استعمال کریں (سست استفسارات: 500؛ تیز استفسارات: 5000)۔ سست استفسارات کے حدود کا اطلاق متعدد قدروں کے حامل پیرامیٹر پر بھی ہو سکتا ہے۔; معطیٰ لہ: bot اور sysop

ڈیٹا کی اقسام

میڈیاویکی کو دیا جانے والا اِن پٹ NFC-normalized UTF-8 کی شکل میں ہونا چاہیے۔ گرچہ میڈیاویکی دوسرے اقسام کے اِن پٹ کو مطلوبہ شکل میں تبدیل کر سکتا ہے لیکن اس عمل کی بدولت (مثلاً ترامیم مع MD5 checks جیسی) بعض کارروائیوں کی ناکامی کا امکان ہے۔

ایک پیرامیٹر کی کئی قدریں درج کرنی ہوں تو بالعموم انھیں پائپ کی علامت کے ساتھ لکھا جاتا ہے، مثلاً param=value1|value2 یا param=value1%7Cvalue2۔ اگر کسی قدر میں پائپ کی علامت لگانا ضروری ہو تو انھیں باہم ممتاز رکھنے کے لیے U+001F کا استعمال کریں اور قدر سے قبل U+001F درج کریں۔ مثلاً param=%1Fvalue1%1Fvalue2۔

boolean: بولین پیرامیٹر ایچ ٹی ایم ایل چیک باکس کی طرح کام کرتے ہیں۔ چنانچہ قدر سے قطع نظر، اگر پیرامیٹر لکھا جائے تو true ہوگا۔ اگر false مطلوب ہو تو پیرامیٹر کو مکمل طور پر حذف کر دیں۔
expiry: میعاد کے خاتمہ کی جانب اشارہ کرنے والی قدریں اضافی (مثلاً 5 months یا 2 weeks) اور مطلق (مثلاً 2014-09-18T12:34:56Z) دونوں طرح ہو سکتی ہیں۔ جس کی میعاد کبھی ختم نہ ہو، اس کے لیے infinite، indefinite، infinity یا never استعمال کریں۔
timestamp: تاریخوں اور اوقات کو مختلف شکلوں میں لکھا جا سکتا ہے۔ مزید تفصیلات کے لیے میڈیاویکی کے اس صفحہ سے رجوع کریں۔ تاہم ISO 8601 کی تاریخ اور وقت کا استعمال بہتر ہوگا: 2001-01-15T14:56:00Z نیز موجودہ وقت و تاریخ کو درج کرنے کے لیے now کا استعمال بھی جا سکتا ہے۔

سانچے کے پیرامیٹر

سانچوں کے پیرامیٹر ان صورتوں کی بھی مدد کرتے ہیں جب اےپی آئی ماڈیول کو کسی دوسرے پیرامیٹر کی ہر قدر کے لیے کسی منفرد قدر کی ضرورت ہو۔ مثلاً پھلوں کی درخواست کے لیے کوئی اےپی آئی ماڈیول موجود ہو تو اس میں fruits نامی پیرامیٹر ہو سکتا ہے تاکہ پھلوں کا نام اور قسم وغیرہ کا تعین کیا جا سکے، نیز {fruit}-quantity پیرامیٹر بھی ہوگا تاکہ درخواست میں پھلوں کی مقدار بھی بتائی جا سکے۔ اس صورت میں اےپی آئی کلائنٹ جسے 1 سیب، 5 کیلے اور 20 اسٹرابیری درکار ہو، کچھ اس طرز پر اپنی درخواست بھیج سکتا ہے: fruits=apples|bananas|strawberries&apples-quantity=1&bananas-quantity=5&strawberries-quantity=20

اعتراف نامہ

اےپی‌آئی کے ترقی دہندگان:

یوری استراخان (تخلیق کار، نمایاں ڈویلپر ستمبر 2006ء تا ستمبر 2007ء)
روان کاتو (نمایاں ڈویلپر ستمبر 2007ء تا 2009ء)
وکٹر واسیلیف
بریان ٹونگ مینھ
سام ریڈ
بریڈ یورش (نمایاں ڈویلپر 2013ء تا 2020ء)

براہ کرم اپنے تبصروں، تاثرات، تجاویز اور سوالات mediawiki-api@lists.wikimedia.org پر روانہ کریں یا https://phabricator.wikimedia.org/ پر نقص کی اطلاع دیں۔