API:Etiquette
Bu sayfa MediaWiki Eylem API'si belgelerinin bir parçasıdır. |
Kısacası bu sayfa:
|
Bu sayfa, API kullanılırken uyulması gereken en iyi uygulamaları içerir. See also the official guidelines about API usage on Wikimedia Foundation Governance wiki.
Davranış
İstek sınırı
Okuma isteklerinde zor ve hızlı bir sınır yoktur, ancak düşünceli olun ve bir siteyi kaldırmamaya çalışın. Çoğu sistem hizmetlisi, sitelerinin kararlılığını tehlikeye atarsanız sizi belirsiz bir şekilde engelleme hakkını saklı tutar.
Yeni bir istek göndermeden önce bir isteğin bitmesini beklemek, isteklerinizi paralel yerine seri olarak yapmak güvenli bir talep oranıyla sonuçlanmalıdır. Ayrıca, bir istekte birden fazla öğe istemeniz de önerilir:
- Her başlık için yeni bir istek yapmak yerine mümkün olduğunda boru karakterini (
|
) kullanmak, örneğintitles=PageA|PageB|PageC
.
- Başka bir istekten her sonuç için istek yapmak yerine jeneratör kullanmak.
- Bant genişliği kullanımını azaltmak için
Accept-Encoding: gzip
ayarlayarak API çağrıları yaparken GZip sıkıştırmasını kullanın.
Düzenleme yapan, durumu değiştiren veya başka bir şekilde salt okunur olmayan istekler, ücret sınırlamasına tabidir. Uygulanmakta olan kesin ücret sınırı, işlem türüne, kullanıcı haklarınıza ve istekte bulunduğunuz web sitesinin yapılandırmasına bağlı olabilir. Sizin için geçerli olan sınırlar, action=query&meta=userinfo&uiprop=ratelimits API uç noktasına erişilerek belirlenebilir.
İstek oranı sınırına ulaştığınızda, ratelimited
hata koduyla bir API hata yanıtı alırsınız. Bu hatayla karşılaştığınızda, bu isteği yeniden deneyebilirsiniz, ancak sonraki istekler arasındaki süreyi artırmalısınız. Bunun için ortak bir strateji Üstel geri çekilmedir.
Revizyonların ayrıştırılması
revid
parametresini kullanarak belirli bir revizyon numarasından sonuçları sorgulamak mümkün olsa da, bu sunucular için pahalı bir işlemdir.
Belirli bir düzeltmeyi almak için oldid
parametresini kullanın. Örneğin:
Maxlag parametresi
Göreviniz etkileşimli değilse, yani bir kullanıcı sonucu beklemiyorsa, maxlag
parametresini kullanmalısınız.
maxlag
parametresinin değeri tamsayı saniye olmalıdır.
Örneğin:
Bu, sunuculardaki yük yüksek olduğunda görevinizin çalışmasını engelleyecektir. Daha yüksek değerler daha agresif davranış anlamına gelir, daha düşük değerler daha iyidir.
Ayrıntılar için Manual:Maxlag parameter sayfasına bakın.
Kullanıcı-Aracı başlığı
Açıklayıcı bir Kullanıcı Aracısı başlığı ayarlamak en iyi yöntemdir.
Bunu yapmak için Kullanıcı Aracısı: istemci adı/sürüm (iletişim bilgileri ör. kullanıcı adı, e-posta) çerçevesi/sürüm ...
kullanın.
Örneğin PHP'de:
ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) UsedBaseLibrary/1.4');
Popüler bir web tarayıcısının kullanıcı aracısını kopyalamayın. Bu, bir sorun ortaya çıktığında nereden geldiğini takip etmenin kolay olmasını sağlar.
API'yi tarayıcı tabanlı JavaScript'ten çağırıyorsanız, tarayıcıya bağlı olarak User-Agent
üst bilgisini etkileyemeyebilirsiniz.
Bu sorunu gidermek için Api-User-Agent
üstbilgisini kullanın.
Daha fazla ayrıntı için m:Kullanıcı-Aracı politikası sayfasına bakın.
Veri biçimleri
Tüm yeni API kullanıcıları JSON kullanmalıdır . Ayrıntılar için API:Veri biçimleri sayfasına bakın.
Performans
Eylem API'sini kullanarak verileri toplu olarak indirmek her zaman son derece verimli değildir. On Wikimedia wikis, there are faster ways to get data in bulk, see m:Research:Data and wikitech:Portal:Data Services for more details.
Other notes
If your requests obtain data that can be cached for a while, you should take steps to cache it, so you don't request the same data over and over again. Some clients may be able to cache data themselves, but for others (particularly JavaScript clients), this is not possible.
Whenever you're reading data from the web service API, you should try to use GET requests if possible, not POST, as the latter are not cacheable and, in multi-datacenter configurations (including Wikimedia sites), may go to a farther data center.
In exceptional cases where you really need to use POST for a read request, such as calling action=parse
with a long string of wikitext, consider setting the Promise-Non-Write-API-Action: true
header.
This helps ensure that your POST request is processed by an application server in the closest data center, if appropriate.
There is no need to set this header for GET requests, and neither should it be set when making cross-wiki requests within a wiki family using CentralAuth; see görev T91820.
Ayrıca bakınız
- Official guidelines about API usage on Wikimedia Foundation Governance wiki
- API:Anasayfa - Hızlı başlangıç kılavuzu.
- API:Ratelimit & API:Ratelimit/Wikimedia sites
- MediaWiki Interfaces Team tarafından korunur.
- Canlı sohbet (IRC): #mediawiki-core bağlan
- Sorun izleyicisi: Phabricator MediaWiki-Action-API (Sorun bildir)