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. The method of registration also depends on the module type.


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

Dönüş hataları
, çeşitli kontroller yapmak için çeşitli yöntemler içerir, örneğin,


 * Bir parametre kümesinden tam olarak sağlandığını iddia etmeniz gerekiyorsa, kullanın.
 * Bir parametre kümesinden en fazla birinin sağlandığını iddia etmeniz gerekiyorsa, kullanın.
 * Bir parametre kümesinden en az birinin sağlandığını iddia etmeniz gerekiyorsa, kullanın.
 * Kullanıcının belirli hakları olduğunu iddia etmeniz gerekiyorsa, kullanın.
 * Kullanıcının belirli bir sayfada işlem yapabileceğini iddia etmeniz gerekiyorsa, kullanın.
 * Kullanıcı engellenirse (ve modülünüz için önemliyse),  nesnesini  öğesine iletin.

Ancak genellikle kendi hatanızı yükseltmeniz gereken durumlarda karşılaşırsınız. Bunu yapmanın genel yolu çağırmaktır, ancak hata bilgisiyle   varsa bunun yerine  geçebilirsiniz.

Bir hata yerine uyarı vermeniz gerekiyorsa, kullanımdan kaldırma uyarısı ise veya  kullanın.

Belgelendirme
API, MediaWiki'nin uluslararasılaştırma mekanizması kullanılarak belgelenmiştir. Gerekli mesajlar genellikle modülün "path" temel alan varsayılan isimlere sahiptir. Eylem ve biçim modülleri için yol, kayıt sırasında kullanılan modülün adıyla aynıdır. Sorgu alt modülleri için, "query+" önekine sahip addır.

Her modülün tek satırlık açıklaması olması gereken  bir iletiye ihtiyacı olacaktır. Ek yardım metni gerekirse,  ile oluşturulabilir. Her parametrenin  mesajına ihtiyacı vardır ve   kullanan parametrelerin de her değer için   ihtiyacı vardır.

API belgeleriyle ilgili daha fazla ayrıntı altında edinilebilir.

Uzantılar, Wikimedia'da ek API belgeleri de tutabilir. Bu, uzantının ana sayfasında veya daha fazla yer gerekirse,  veya alt sayfalarında (ör.,  veya ) yer almalıdır. API ad alanı, MediaWiki çekirdeğinin API'si için ayrılmıştır.

Temel modülleri genişletme
MediaWiki 1.14'ten bu yana, çekirdek modüllerin işlevselliğini aşağıdaki kancaları kullanarak genişletmek mümkündür:


 * - modülün parametre listesini eklemek veya değiştirmek için
 * - modülün parametre açıklamalarını eklemek veya değiştirmek için
 * - modül yürütüldükten sonra (ancak sonuç çıkmadan önce)
 * ,  ve   modülleri için  kullanın
 * Modül jeneratör modunda çalıştırılırsa, bunun yerine çağıracaktır

API işlevine sahip uzantıların listesi
API'ya eklenen veya API'yi genişleten uzantı örnekleri için sayfasına  bakın.

Uzantınızı test etme

 * [/api.php api.php] ziyaret edin ve modül veya sorgu alt modülü için oluşturulan yardıma gidin. Uzantınızın yardım bilgileri doğru olmalıdır.
 * olarak verdiğiniz örnek URL'ler "Örnekler" altında görünmelidir, tıklamayı deneyin.
 * Sorgu dizesindeki URL parametrelerini atlayın ve yönetin, uzantınızın yanıtını kontrol edin.
 * Special:ApiSandbox syfasını ziyaret edin ve API'nizi etkileşimli olarak keşfedin.
 * Uzantınızla ilgili ek bilgileri görmek için sayfasını ziyaret edin.