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

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

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

اصل ماڈیول

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

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

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

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

acquiretempusername
اگر عارضی کھاتے کی تخلیق فعال ہو اور موجودہ صارف داخل نہ تو کسی عارضی صارف کا صارف نام اخذ کر کے اسے موجودہ نشست میں رکھ دیتا ہے۔ اگر وہ نام پہلے سے ہی رکھا جا چکا ہے تو جواب میں وہ نام لوٹا دیا جائے گا۔
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
کھاتے کو کسی دوسرے فراہم کنندہ سے ہٹا کر موجودہ صارف سے مربوط کرتا ہے۔
login
لاگ ان ہو کر توثیقی کوکیز حاصل کرتا ہے۔
logout
لاگ آؤٹ ہو کر نشست کے سارے ڈیٹا کو صاف کرتا ہے۔
managetags
ٹیگوں کی تبدیلی سے متعلق انتظامی امور انجام دیتا ہے۔
mergehistory
صفحہ کے تاریخچوں کو ضم کرتا ہے۔
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
زیر نظر صفحات کے اطلاع نامہ کے وقت و تاریخ کو تازہ کرتا ہے۔
setpagelanguage
صفحہ کی زبان تبدیل کرتا ہے۔
spamblacklist
فاضل کاری کی فہرست سیاہ کے خلاف ایک یا ایک سے زائد یوآرایل کی توثیق کریں۔
tag
انفرادی نوشتوں یا نوشتہ کے اندراجات سے تبدیلی کے ٹیگوں کو ہٹاتا یا ان میں ٹیگوں کو شامل کرتا ہے۔
templatedata
TemplateData نامی توسیع کے محفوظ کردہ ڈیٹا کو اخذ کرتا ہے۔
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.
webapp-manifest
Returns a webapp manifest.
categorytree
داخلی۔ Internal module for the CategoryTree extension.
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.
editcheckreferenceurl
داخلی۔ Check the status of a URL for use as a reference.
scribunto-console
داخلی۔ Internal module for servicing XHR requests from the Scribunto console.
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).
ذیل کی قدروں میں سے کوئی ایک: acquiretempusername، block، changeauthenticationdata، changecontentmodel، checktoken، clearhasmsg، clientlogin، compare، createaccount، delete، edit، emailuser، expandtemplates، feedcontributions، feedrecentchanges، feedwatchlist، filerevert، help، imagerotate، import، linkaccount، login، logout، managetags، mergehistory، move، opensearch، options، paraminfo، parse، patrol، pfautocomplete، pfautoedit، protect، purge، query، removeauthenticationdata، resetpassword، revisiondelete، rollback، rsd، setnotificationtimestamp، setpagelanguage، spamblacklist، tag، templatedata، unblock، undelete، unlinkaccount، upload، userrights، validatepassword، watch، webapp-manifest، categorytree، cspreport، editcheckreferenceurl، scribunto-console، 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
The value must be no less than 0.
طے شدہ: 0
maxage

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

Type: integer
The value must be no less than 0.
طے شدہ: 0
assert

اگر user ہو تو صارف کے داخل ہونے کی، anon درج کرنے کی صورت میں صارف کے داخل نہ ہونے کی اور 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

نظامی پیغاموں کے ترجمے کے لیے استعمال کی جانے والی زبان۔ action=query&meta=siteinfo&siprop=languages جواب میں زبانوں کے رموز فراہم کرتا ہے۔ نیز آپ موجودہ صارف کی لسانی ترجیح کو استعمال کرنے کے لیے user اور پیش نظر ویکی کے مندرجات کی زبان کو استعمال کرنے لیے content کا استعمال بھی کر سکتے ہیں۔

طے شدہ: user
variant

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

errorformat

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

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

انتباہات اور نقائص کے لیے استعمال کی جانے والی زبان۔ action=query&meta=siteinfo&siprop=languages جواب میں زبانوں کے رموز کی فہرست بھیجتا ہے۔ پیش نظر ویکی کے مندرجات کی زبان استعمال کرنے کے لیے content کا، یا uselang پیرامیٹر کی طرح یکساں قدر استعمال کرنے کے لیے uselang کا استعمال کریں۔

طے شدہ: uselang
errorsuselocal

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

طرز: بولین (تفصیلات)
مثالیں
اصل ماڈیول کی رہنما تفصیلات۔
api.php?action=help [تختۂ مشق میں کھولیں]
ایک صفحہ میں تمام رہنمائیاں۔
api.php?action=help&recursivesubmodules=1 [تختۂ مشق میں کھولیں]
اجازت:
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/ پر نقص کی اطلاع دیں۔