API:Uygulama Stratejisi
Bu sayfa MediaWiki Eylem API'si belgelerinin bir parçasıdır. |
Bu, MediaWiki API makinesinin temelde uygulanmasını açıklar. Kodunuzda istemcilerin kullanması için bir API sağlamak istiyorsanız, API:Uzantılar sayfasını okuyun.
Dosya/Modül Yapısı
api.php
, viki kökünde bulunan giriş noktasıdır. API:Anasayfa#Uç nokta bölümüne bakın.includes/api
, API ile ilgili tüm dosyaları içerecek, ancak hiçbirinin giriş noktası olarak kullanılmasına izin verilmeyecektir.- Tüm API sınıfları ortak bir soyut sınıf
ApiBase
üzerinden türetilmiştir. Temel sınıf, parametre ayrıştırma, profil oluşturma ve hata işleme gibi ortak işlevler sağlar. ApiMain
,api.php
tarafından başlatılan ana sınıftır.action=XXX
parametresine göre hangi modülün çalıştırılacağını belirler.ApiMain
ayrıca, çıkışı verisi dizisini ve ilgili yardımcı işlevleri içerenApiResult
sınıfının bir örneğini oluşturur. Son olarak,ApiMain
, veriyiApiResult
üzerinden XML/JSON/PHP veya başka bir biçimde istemciye çıkaracak biçimlendirme sınıfını başlatır.ApiBase
üzerinden türetilen herhangi bir modül, örnekleme sırasındaApiMain
bir örneğine bir kaynak alır, böylece modül yürütme sırasında sonuç nesnesi gibi paylaşılan kaynakları alabilir.
Sorgu modülleri
ApiQuery
, alt modülleri yürüttüğü içinApiMain
ile benzer davranır. Her bir alt modül,ApiQueryBase
üzerinden türetilir (üst düzey bir modül olanApiQuery
kendisi hariç). Örnekleme sırasında, alt modüller ApiQuery örneğine bir kaynak alır.- Tüm uzantı sorgu modülleri 3 veya daha fazla harfli önek kullanmalıdır. Çekirdek modüller 2 harfli ön ek kullanır.
ApiQuery
yürütme planı:- Gerekli alt modülleri belirlemek için paylaşılan
list/prop/meta
sorgu parametrelerini alın. - Bir
ApiPageSet
nesnesi oluşturun ve onutitles/pageids/revids
parametrelerinden doldurun.pageset
nesnesi, sorgu modüllerinin birlikte çalışacağı sayfaların veya revizyonların listesini içerir. - İstenirse, başka bir
PageSet
oluşturmak için bir oluşturucu modülü çalıştırılır. UNIX'teki boru akışlarına benzer. Verilen sayfalar, diğer tüm modüllerin üzerinde çalışması için başka bir sayfa kümesi üreten oluşturucu girdisidir.
- Gerekli alt modülleri belirlemek için paylaşılan
- Sorgu devam ettirme gereksinimleri:
- SQL sorgusu tamamen sıralanmalıdır. Başka bir deyişle, sorgu,
WHERE
yan tümcesinde veyaORDER BY
yan tümcelerinde sabitler olarak bazı benzersiz anahtarların tüm sütunlarını kullanıyor olmalıdır.- MySQL'de bu bir özel veya, Foo ve Bar sorgulamalarının başlığa göre sıralanması gerektiği, ancak ad alanına göre sıralanmaması gereken (ad alanı 0 sabittir), Foo ve Talk:Foo ad alanına göre sıralanmalı ancak başlığa göre sıralanmamalıdır (başlık sabit "Foo") ve Foo ve Talk:Bar hem ad alanına hem de başlığa göre sıralanmalıdır.
- SQL sorgusu dosya sıralaması yapmamalıdır.
setContinueEnumParameter()
ile verilen değer,ORDER BY
yan tümcesindeki tüm sütunları içermelidir.- Devam ederken,
WHERE
cümlesine tek bir bileşik koşul eklenmelidir. SorgudaORDER BY column_0, column_1, column_2
varsa, bu koşul aşağıdaki gibi görünmelidir:
- SQL sorgusu tamamen sıralanmalıdır. Başka bir deyişle, sorgu,
(column_0 > value_0 OR (column_0 = value_0 AND (column_1 > value_1 OR (column_1 = value_1 AND (column_2 >= value_2) )) ))
Tabii ki, ORDER BY
sütunlarınız DESC
kullanıyorsa "<" için ">" değiştirin.
Değerlerde SQL enjeksiyonundan kaçındığınızdan emin olun.
Dahili veri yapıları
- Sorgu API'si, çok başarılı bir küresel iç içe geçmiş
array()
yapısına sahipti. Çeşitli modüller, son olarak, yazıcılardan biri (çıkış modülleri) tarafından istemci için işlenene kadar, bu dizinin birçok farklı noktasına veri parçaları ekleyecektir. API için, bu diziyi tek tek yaprak düğümleri eklemek üzere yardımcı işlevlere sahip bir sınıf olarak sarmalamanızı öneririz.
Hata/durum raporlama
Şimdilik hata bilgilerini normal sonuç olarak aynı yapılandırılmış çıkışının içine dahil etmeye karar verdik (seçenek #2).
Sonuç olarak, standart HTTP hata kodlarını kullanabiliriz veya her zaman uygun şekilde biçimlendirilmiş bir veri döndürebiliriz:
- HTTP kodunu kullanma
void header( string reason_phrase [, bool replace [, int http_response_code]] )
header()
, işlemin döndürme durumunu ayarlamak için kullanılabilir.
reason_phrase
tüm olası değerlerini tanımlayabiliriz, bu nedenle başarısız oturum açma için code=403
ve phrase="BadPassword"
döndürebiliriz, oysa herhangi bir başarı için başlığı değiştirmeden basitçe yanıtı döndürürdük.
Artılar: Bu bir standart. İstemci her zaman HTTP hatalarıyla uğraşmak zorundadır, bu nedenle sonuç için HTTP kodunu kullanmak, istemcinin gerçekleştirmesi gereken ayrı bir hata işlemeyi ortadan kaldırır. İstemci birden fazla biçimde veri talep edebileceğinden, geçersiz bir format parametresi yine de düzgün bir şekilde ele alınacaktır, çünkü bu yalnızca başka bir http hata kodu olacaktır.
Eksiler: ...
- Hata bilgilerini uygun bir yanıtın içine ekleyin
Bu yöntem her zaman uygun şekilde biçimlendirilmiş bir yanıt nesnesi döndürür, ancak hata durumu/açıklaması bu nesnenin içindeki tek değerler olacaktır. Bu, mevcut Sorgu API'nin durum kodlarını döndürme şekline benzer.
Artılar: HTTP hata kodları, veriler (mantıksal hatalar) için değil, yalnızca ağ oluşturma sorunları için kullanılır. Mevcut HTTP hata kodlarına bağlı değiliz.
Eksiler: Veri format parametresi doğru şekilde belirtilmezse, çıkış verilerinin biçimi nedir? Uygulama, bir hatayı bilmesi için nesneyi ayrıştırmalıdır (perf?). Hata kontrol kodunun hem bağlantı hem de veri ayrıştırma seviyelerinde olması gerekir.
Basmakalıp kodu
It has been suggested that this page or section be merged with API:Extensions#ApiSampleApiExtension.php.(Tartış) |
Basit API modülü |
---|
<?php
class Api<modül adı> extends ApiBase {
public function __construct( $main, $action ) {
parent::__construct( $main, $action );
}
public function execute() {
}
public function getAllowedParams() {
return array(
'<parametre adı>' => array(
ApiBase::PARAM_TYPE => array( 'foo', 'bar', 'baz' ),
),
);
}
public function getParamDescription() {
return array(
'<parametre adı>' => '<parametre açıklaması>',
);
}
public function getDescription() {
return '<Modül açıklaması burada>';
}
public function getExamples() {
return array(
'api.php?action=<modül adı>&<parametre adı>=foo'
);
}
public function getHelpUrls() {
return '';
}
}
|