API:Uzantılar

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 ApiBase 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 action parametresi için değer sağlayan modüller ApiBase alt sınıfını içermelidir. APIModules anahtarı kullanılarak extension.json olarak kaydedilmelidirler.

biçim modülleri

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

sorgu modülleri

prop, list veya meta parametreleri için action=query ile bir değer sağlayan modüller ApiQueryBase (bir jeneratör olarak kullanılamazsa) veya ApiQueryGeneratorBase (bir jeneratör olarak kullanılabilirse) alt sınıfına sahip olmalıdır. $APPropModules, APIListModules veya APIMetaModules anahtarı kullanılarak extension.json 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 $hook1 (eylem ve format modülleri için) ve $hook2 (sorgu alt modülleri için) kancaları kullanılarak koşullu olarak kaydedilebilir. Modules may also be registered conditionally using the ApiMain::moduleManager (for action and format modules) and ApiQuery::moduleManager (for query submodules) hooks.

Uygulama

Önek

API modülünüzün yapıcısında parent::__construct() öğ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. For action and format modules, the prefix is optional.

Parametreler

Çoğu modül parametre gerektirir. Bunlar $getAllowedParams 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 $ApiBase tarafından tanımlanan $param sabitlerini kullanarak parametrenin özelliklerini tanımlayan bir dizi olduğu ilişkisel bir dizidir. These are defined by implementing getAllowedParams(). The return value is an associative array where keys are the (unprefixed) parameter names and values are either the scalar default value for the parameter or an array defining the properties of the parameter using the PARAM_* constants defined by ApiBase.

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

	protected function getAllowedParams() {
		return [
			// Varsayılan değeri olan isteğe bağlı bir parametre
			'simple' => 'value',

			// Gerekli bir parametre
			'required' => [
				ApiBase::PARAM_TYPE => 'string',
				ApiBase::PARAM_REQUIRED => true,
			],

			// Bir listeden birden fazla değeri kabul eden bir parametre
			'variable' => [
				// Varsayılan değer kümesi
				ApiBase::PARAM_DFLT => 'foo|bar|baz',
				// Tüm olası değerler
				ApiBase::PARAM_TYPE => [ 'foo', 'bar', 'baz', 'quux', 'fred', 'blah' ],
				// Birden çok değerin kabul edildiğini belirtin
				ApiBase::PARAM_ISMULTI => true,
				// Standart "değer başına" belge mesajlarını kullanın
				ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
			],

			// Standart bir "limit" parametresi. Genellikle bu standarttan farklı olmamak en iyisidir.
			'limit' => [
				ApiBase::PARAM_DFLT => 10,
				ApiBase::PARAM_TYPE => 'limit',
				ApiBase::PARAM_MIN => 1,
				ApiBase::PARAM_MAX => ApiBase::LIMIT_BIG1,
				ApiBase::PARAM_MAX2 => ApiBase::LIMIT_BIG2,
			],
		];
	}

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 execute() yöntemine gider. Bu kod, giriş parametrelerini almak için genellikle $this→extractRequestParams() ve herhangi bir çıktı eklemek için ApiResult nesnesini almak için $this→getResult() kullanır.

Sorgu destekli alt modüller, üzerinde çalışılacak sayfa grubuna erişmek için $this→getPageSet() kullanmalıdır.

Oluşturucu olarak kullanılabilecek sorgu alt modüllerinin, oluşturulan sayfalarla doldurulması gereken ApiPageSet bir geçmiş olan executeGenerator() uygulaması gerekecektir. Bu durumda, ApiResult 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, $this→getMain()→setCacheMode() çağırarak önbelleğe almaya izin verebilirsiniz. Bu, istemcilerin önbelleğe almayı gerçekten etkinleştirmek için maxage veya smaxage parametrelerini geçmesini gerektirir. Önbelleği $this→getMain()→setCacheMaxAge() çağırarak da zorlayabilirsiniz.

Sorgu modülleri için bu yöntemleri çağırmayın. Bunun yerine getCacheMode() 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 'csrf' düzenleme anahtarı) döndürerek needsToken() yöntemini uygulayın. API temel kodu, istemcilerin API isteklerinde sağladıkları anahtarı token 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 ApiQueryTokensRegisterTypes kancası kullanın.

Master veritabanı erişimi

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

Dönüş hataları

ApiBase, ç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, $this→requireOnlyOneParameter() kullanın.

• Bir parametre kümesinden en fazla birinin sağlandığını iddia etmeniz gerekiyorsa, $this→requireMaxOneParameter() kullanın.

• Bir parametre kümesinden en az birinin sağlandığını iddia etmeniz gerekiyorsa, $this→requireAtLeastOneParameter() kullanın.

• Kullanıcının belirli hakları olduğunu iddia etmeniz gerekiyorsa, $this→checkUserRightsAny() kullanın.

• Kullanıcının belirli bir sayfada işlem yapabileceğini iddia etmeniz gerekiyorsa, $this→checkTitleUserPermissions() kullanın.

• Kullanıcı engellenirse (ve modülünüz için önemliyse), Block nesnesini $this→dieBlocked() öğesine iletin.

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

Bir hata yerine uyarı vermeniz gerekiyorsa, kullanımdan kaldırma uyarısı ise $this→addWarning() veya $this→addDeprecation() 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. 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+.

Her modülün tek satırlık açıklaması olması gereken apihelp-$path-summary bir iletiye ihtiyacı olacaktır. Ek yardım metni gerekirse, apihelp-$path-extended-description ile oluşturulabilir. Her parametrenin apihelp-$path-param-$name mesajına ihtiyacı vardır ve PARAM_HELP_MSG_PER_VALUE kullanan parametrelerin de her değer için apihelp-$path-paramvalue-$name-$value ihtiyacı vardır.

API belgeleriyle ilgili daha fazla ayrıntı API:Yerelleştirme altında edinilebilir.

Uzantılar, Wikimedia'da ek API belgeleri de tutabilir. Bu, uzantının ana sayfasında veya daha fazla yer gerekirse, Extension:<ExtensionName>/API veya alt sayfalarında (ör. CentralAuth , MassMessage veya StructuredDiscussions ) 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:

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

API işlevine sahip uzantıların listesi

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

Uzantınızı test etme

• 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.
  • getExamplesMessages() 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 $api sayfasını ziyaret edin.

api.php?action=paraminfo&modules=myext [ApiSandbox'ta deneyin]