API:Extensions/ar

تغطي هذه الوثيقة إنشاء وحدة آبي في امتداد للاستخدام مع ميدياويكي 1.30 والإصدارات الأحدث.



إنشاء وحدة والتسجيل
كافة وحدات واجهة برمجية التطبيقات هي فئات فرعية من فئة ، إلا أن بعض أنواع الوحدات البرمجية تستخدم فئة أساسية مشتقة. طريقة التسجيل تعتمد أيضًا على نوع الوحدة البرمجية.


 * وحدات action البرمجية
 * يجب أن تكون الوحدات البرمجية التي تقدم قيمة لمعامل  الرئيسي فئة فرعية من . يجب أن تكون مسجلة في   مستخدمًا مفتاح.


 * وحدات format البرمجية
 * يجب أن تكون الوحدات البرمجية التي تقدم قيمة لمعامل  الرئيسي فئة فرعية من . يجب أن تكون مسجلة في   مستخدمًا مفتاح  . يندر للغاية أن يحتاج أي امتداد لإضافة وحدة format برمجية.


 * وحدات query البرمجية الفرعية
 * يجب أن تكون الوحدات البرمجية التي تقدم قيمة لمعاملات  أو   أو   للوحدة   فئة فرعية من  (لو لم تكن مستخدمة في صفة مولّد) أو  (لو كانت مستخدمة في صفة مولّد). يجب أن تكون مسجلة في   مستخدمًا مفاتيح   أو   أو.

في كافة الحالات، تصبح قيمة مفتاح التسجيل عنصر يحتوي على اسم الواحدة البرمجية (أي قيمة المعامل) في صفة مفتاح واسم الفئة في صفة قيمة. يجوز أيضًا تسجيل الوحدات البرمجية تسجيلًا شرطيًا مستخدمًا وصلات (للوحدات البرمجية من نوع action وformat) ومستخدمًا  (وحدات query البرمجية الفرعية).

بادئة
في باني وحدتك البرمجية المخصصة لواجهة برمجة التطبيقات، حينما تستدعي يمكنك تحديد بادئة اختيارية لمعاملات وحدتك البرمجية. (في أعمال التوثيق المولّدة لهذه الوحدة البرمجية ستظهر هذه البادئة، لو وجدت، في أقواس في العنوان الرئيسي للوحدة البرمجية.) لو كانت وحدتك البرمجية هي وحدة برمجية فرعية لأغراض الاستفسار «query» سيتطلب الأمر وجود بادئة، منذ أن الجهاز العميل يمكنه استدعاء وحدات برمجية فرعية عدة مستخدمًا معاملاته الخاصة في طلب واحد. أما في الوحدات البرمجية لأغراض «action» و«format»، تصبح البادئة أمرًا اختياريًا.

معاملات
أغلب الوحدات البرمجية تتطلب وجود معاملات. هذه المعاملات معرفّة عن طريق تنفيذ. القيمة الراجعة هي صفيف ترابطي الذي تكون فيه المفاتيح هي أسماء المعاملات (خالية من بادئات) والقيم هي إما قيمة متدرجة افتراضية للمعامل أو صفيف يعرّف خصائص المعامل مستخدمًا ثوابت  المعرفة في.

يبين المثال الصياغة النحوية وبعض من ثوابت  المعتادة.

توثّق المعاملات باستخدام آلية ميدياويكي لأعمال التدويل. طالع قسم #التوثيق لمزيد من التفاصيل.



التنفيذ والناتج
يذهب الكود البرمجي الذي ينفّذ بالفعل الوحدة البرمجية في طريقة. سيستخدم هذا الكود البرمجي بوجه عام للحصول على معاملات الإدخال، وسيستخدم  للحصول على عنصر  لإضافة أي خرج له.

Query prop submodules should use to access the set of pages to operate on.

Query submodules that can be used as generators will also need to implement which is passed an  that should be filled with the generated pages. In this case, the  should generally not be used.

الحفظ المؤقت
By default API responses are marked as not cacheable ('Cache-Control: private')!

This still requires clients pass the  or   parameters to actually enable caching.

For query modules, do not call those methods. You can allow caching by instead implementing.

في كلتا الحالتين، تأكد من أن البيانات الخاصة غير معروضة.



التعامل مع الرموز
If your action module changes the wiki in any way, it should require a token of some kind. To have this handled automatically, implement the  method, returning the token that your module requires (probably the   edit token). The API base code will then automatically validate the token that clients provide in API requests in a  parameter.

If you don't want to use a token that is part of core, but rather a custom token with your own permission checks, use hook to register your token.



الوصول إلى قاعدة البيانات الرئيسية
If your module accesses the master database, it should implement the  method to return.



الأخطاء المردودة
includes several methods for performing various checks, for example,


 * If you need to assert that exactly one of a set of parameters was supplied, use.
 * If you need to assert that at most one of a set of parameters was supplied, use.
 * If you need to assert that at least one of a set of parameters was supplied, use.
 * If you need to assert that the user has certain rights, use.
 * If you need to assert that the user can take an action on a particular page, use.
 * If the user is blocked (and that matters to your module), pass the  object to.

But you will often run into cases where you need to raise an error of your own. The usual way to do that is to call, although if you have a  with the error information you could pass it to  instead.

If you need to issue a warning rather than an error, use or  if it's a deprecation warning.

التوثيق
The API is documented using MediaWiki's i18n mechanism. Needed messages generally have default names based on the module's "path". For action and format modules, the path is the same as the module's name used during registration. For query submodules, it's the name prefixed with "query+".

Every module will need a  message, which should be a one-line description of the module. If additional help text is needed,  may be created as well. Each parameter will need a  message, and parameters using   will also need a   for each value.

More details on API documentation are available at.

Extensions may also maintain extra API documentation on Wikimedia. This should be located on the extension's main page or, if more space is required, on pages named  or subpages thereof (e.g., , or ). The API namespace is reserved for the API of MediaWiki core.



توسيع الوحدات البرمجية في اللب البرمجي
Since MediaWiki 1.14, it's possible to extend core modules' functionality using the following hooks:


 * - to add or modify the module's parameter list
 * - to add or modify the module's parameter descriptions
 * - to do something after the module has been executed (but before the result has been output)
 * Use for ,   and   modules
 * If the module is run in generator mode, will be called instead



قائمة الامتدادات التي تحتوي على وظائف واجهة برمجة التطبيقات
See for examples of extensions that add to or extend the API.



اختبار امتدادك
Your extension's help information should be correct.
 * Visit [/api.php api.php] and navigate to the generated help for your module or query submodule.
 * The example URLs you provided in  should appear under "Examples", try clicking them.
 * Omit and mangle URL parameters in the query string, check your extension's response.
 * Visit Special:ApiSandbox and interactively explore your API.
 * To see additional information about your extension: