API:Extensions/tr

Bu belge, MediaWiki 1.30 ve sonraki sürümlerle kullanım için bir uzantıda bir API modülü oluşturmayı kapsar.

Modül oluşturma ve kaydetme
Tüm API modülleri alt sınıflarıdır, ancak bazı modül türleri türetilmiş bir temel sınıf kullanır. Kayıt yöntemi modül tipine de bağlıdır.


 * eylem modülleri
 * Ana  parametresi için değer sağlayan modüller  alt sınıfını içermelidir.   anahtarı kullanılarak   olarak kaydedilmelidirler.


 * biçim modülleri
 * Ana  parametresi için değer sağlayan modüllerin  alt sınıfı olmalıdır.   anahtarı kullanılarak   biçiminde kaydedilmelidirler. Bir uzantının bir biçim modülü eklemesi çok nadirdir.


 * sorgu modülleri
 * ,  veya   parametreleri için   ile bir değer sağlayan modüller  (bir jeneratör olarak kullanılamazsa) veya  (bir jeneratör olarak kullanılabilirse) alt sınıfına sahip olmalıdır. $APPropModules,   veya   anahtarı kullanılarak   biçiminde kaydedilmelidir.

Her durumda, kayıt anahtarının değeri, anahtar olarak modül adına (yani parametrenin değeri) ve değer olarak sınıf adına sahip bir nesnedir. Modüller ayrıca (eylem ve format modülleri için) ve  (sorgu alt modülleri için) kancaları kullanılarak koşullu olarak kaydedilebilir.

Önek
API modülünüzün yapıcısında  öğesini çağırdığınızda modülünüzün parametreleri için isteğe bağlı bir önek belirleyebilirsiniz. (Bir modülün oluşturulan belgelerinde, varsa bu önek, modül başlığında parantez içinde görünür.) Modülünüz bir sorgu alt modülü ise, bir önek gereklidir, çünkü istemci tek bir istekte her biri kendi parametrelerine sahip birden fazla alt modül çağırabilir. Eylem ve biçim modülleri için önek isteğe bağlıdır.

Parametreler
Çoğu modül parametre gerektirir. Bunlar uygulanarak tanımlanır. Dönüş değeri, anahtarların (önceden düzeltilmemiş) parametre adları ve değerlerinin parametre için skaler varsayılan değer olduğu veya tarafından tanımlanan   sabitlerini kullanarak parametrenin özelliklerini tanımlayan bir dizi olduğu ilişkisel bir dizidir.

Örnek, sözdizimini ve daha yaygın olan  sabitlerini göstermektedir.

Parametreler MediaWiki'nin uluslararasılaştırma mekanizması kullanılarak belgelenmiştir. Ayrıntılar için #Belgeleme bölümüne bakın.

Yürütme ve çıkış
Aslında modülü uygulayan kod yöntemine gider. Bu kod, giriş parametrelerini almak için genellikle ve herhangi bir çıktı eklemek için  nesnesini almak için  kullanır.

Sorgu destekli alt modüller, üzerinde çalışılacak sayfa grubuna erişmek için kullanmalıdır.

Oluşturucu olarak kullanılabilecek sorgu alt modüllerinin, oluşturulan sayfalarla doldurulması gereken bir geçmiş olan  uygulaması gerekecektir. Bu durumda,  genellikle kullanılmamalıdır.

Önbelleğe almak
Varsayılan olarak API yanıtları önbelleklenemez ('Cache-Control: private') olarak işaretlenir! Eylem modülleri için, çağırarak önbelleğe almaya izin verebilirsiniz. Bu, istemcilerin önbelleğe almayı gerçekten etkinleştirmek için  veya   parametrelerini geçmesini gerektirir. Önbelleği çağırarak da zorlayabilirsiniz.

Sorgu modülleri için bu yöntemleri çağırmayın. Bunun yerine uygulayarak önbelleğe almaya izin verebilirsiniz.

Her iki durumda da, özel verilerin gösterilmediğinden emin olun.

Anahtar kullanımı
Eylem modülünüz vikiyi herhangi bir şekilde değiştirirse, bir tür anahtar gerektirir. Bunun otomatik olarak ele alınması için, modülünüzün gerektirdiği anahtarı (muhtemelen  düzenleme anahtarı) döndürerek   yöntemini uygulayın. API temel kodu, istemcilerin API isteklerinde sağladıkları anahtarı  parametresinde otomatik olarak doğrular.

Çekirdeğin parçası olan bir anahtar kullanmak istemiyorsanız, ancak kendi izin denetimlerinizle birlikte özel bir anahtar kullanmak istiyorsanız, anahtarınızı kaydetmek için kancası kullanın.

Master veritabanı erişimi
Modülünüz ana veritabanına erişirse,  döndürmek için   yöntemini uygulamalıdır.

Returning errors
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.

Documentation
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.

Extending core modules
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

List of extensions with API functionality
See for examples of extensions that add to or extend the API.

Testing your extension

 * Visit [/api.php api.php] and navigate to the generated help for your module or query submodule. Your extension's help information should be correct.
 * 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.
 * Visit to see additional information about your extension.