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

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

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

اصل ماڈیول

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

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

مخصوص پیرامیٹر:
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/ پر نقص کی اطلاع دیں۔