API:Page principale

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:Main page and the translation is 100% complete.
Other languages:
العربية • ‎azərbaycanca • ‎български • ‎বাংলা • ‎čeština • ‎dansk • ‎Deutsch • ‎English • ‎Esperanto • ‎español • ‎فارسی • ‎français • ‎हिन्दी • ‎Հայերեն • ‎Bahasa Indonesia • ‎italiano • ‎日本語 • ‎Taqbaylit • ‎ಕನ್ನಡ • ‎한국어 • ‎lietuvių • ‎文言 • ‎मैथिली • ‎मराठी • ‎Nederlands • ‎occitan • ‎polski • ‎پښتو • ‎português • ‎português do Brasil • ‎română • ‎русский • ‎سنڌي • ‎ไทย • ‎Türkçe • ‎українська • ‎Tiếng Việt • ‎粵語 • ‎中文
Cette page fait partie de la documentation de l'API MediaWiki.


MediaWiki action API

v · d · e
Ceci est une présentation de l'API "action". Voir la barre de menu sur la droite pour des sous-catégories plus détaillées et d'autres APIs.

L'action API Médiawiki est un service web qui fournit un accès facile aux fonctionnalités du wiki, de ses données, et de ses méta-données via HTTP, via une URL, se trouvant généralement à l’adresse api.phpManual:api.php. Les clients demandent des "actions" particulières en spécifiant un paramètre action, souvent action=query pour récupérer de l'information. Elle était connue sous le nom d'API MediaWiki, mais MediaWiki offre maintenant d'autres APIs web comme REST API et le service de requêtes Wikidata.

Introduction

Si vous cherchez plutôt une API interne ou une API PHP, voir l’interface d'extension, qui autorise les développeurs PHP à ajouter de nouvelles fonctionnalités à une installation MediaWiki.
Les changements de fonctionnalités dans l'API sont disponibles par inscription à la liste de diffusion mediawiki-api-announce. L'inscription sur la liste est recommandée

L'API action de MediaWiki peut être utilisée pour surveiller une installation MediaWiki, ou créer un robot pour en maintenir une automatiquement. Elle fournit un accès direct et de haut niveau aux données contenues dans les bases de données MediaWiki. Des programmes clients peuvent se connecter à un wiki, obtenir les données, et poster automatiquement les modifications en envoyant des requêtes HTTP au service web. Les clients supportés incluent les robots, les clients web JavaScript légers comme les popups de navigation et LiveRC, les applications utilisateurs finaux comme Vandal Fighter, et les autres sites web (utilitaires Toolforge).

Dans les nouvelles installations MediaWiki, le service web est activé par défaut, mais un administrateur peut le désactiver.

MediaWiki a deux autres interfaces tournées vers l'extérieur :

Un exemple simple

Cette URL demande au service web Anglais de Wikipédia de vous envoyer le contenu de la page principale:

https://en.wikipedia.org/w/api.php?action=query&titles=Main%20Page&prop=revisions&rvprop=content&format=json&formatversion=2

Utilisez n'importe quel langage de programmation pour envoyer une requête HTTP GET pour cette URL (ou consultez simplement ce lien dans votre navigateur), et vous obtiendrez un document JSON qui contient le code source actuel de la page appelée « Main Page ». Changer le format en jsonfm retournera un affichage HTML mis en forme élégamment, utile pour le débogage.

Voici l'URL jsonfm en tant que lien cliquable "plus facile à lire".

api.php?action=query&titles=Main%20Page&prop=revisions&rvprop=content&format=jsonfm&formatversion=2 [essayez dans ApiSandbox]

Prenons l'URL à part pour montrer comment cela fonctionne.

L'URL principale

https://en.wikipedia.org/w/api.php

Ceci est l'URL principale. Cela peut être comparé à la page principale de l'API du service web MediaWiki. Cette URL est l'URL de base pour l'API Wikipédia Anglaise, tout comme https://en.wikipedia.org/wiki/ est l'URL de base pour ce site web.

Si vous écrivez un programme pour utiliser le Wikipédia Anglais, chaque URL que vous utiliserez commencera par cette URL de base. Si vous utilisez une installation MediaWiki différente, vous aurez besoin de trouver son URL de base et de l'utiliser à la place. Tous les wikis Wikimedia ont des URL de base qui suivent ce schéma : 

https://www.mediawiki.org/w/api.php     # API MediaWiki
https://en.wikipedia.org/w/api.php      # API Wikipédia Anglaise
https://nl.wikipedia.org/w/api.php      # API Wikipédia Néerlandaise
https://commons.wikimedia.org/w/api.php # API Wikimedia Commons


Version de MediaWiki : ≥ 1.17

Depuis la révision r75621, nous avons un système RSD pour l'URL de base : cherchez le link rel="EditURI" dans le code source HTML de n'importe quelle page et extrayez l'URL api.php; le lien contient des informations additionnelles. Pour information, sur le wiki il s'agit de : 

<link rel="EditURI" type="application/rsd+xml" href="//www.mediawiki.org/w/api.php?action=rsd" />

Autrement, il n'y a aucune manière sûre de trouver l'URL de base d'un wiki. Si vous êtes chanceux, soit le chemin complet vers index.php ne sera pas caché à travers des règles de redirection étranges, dans ce cas vous n'aurez qu'à récupérer le lien « voir le code source » (ou « historique ») et de remplacer index.php par api.php, soit vous pourrez utiliser le script path par défaut (comme w/api.php).

Maintenant, passons aux paramètres contenus dans la chaîne de requête de l'URL.

format

format=json Ceci demande à l'API du service web de Wikimedia de retourner les données en format JSON. Vous pourriez aussi vouloir essayer le format format=jsonfm pour récupérer une version HTML du résultat, utile pour le débogage. L'API supporte d'autres formats de sortie comme XML et PHP natif, mais il est prévu de supprimer les formats les moins populaires (phab:T95715), il est donc recommandé de ne pas les utiliser.

action

action=query

L'API du service web de MediaWiki implémente de nombreuses actions et les extensions en implémentent encore plus ; L'aide pour l'API générée automatiquement documente toutes les actions disponibles sur un wiki. Dans ce cas, nous utilisons l'action « query » pour récupérer des informations. L'action « query » est une des actions les plus importantes de l'API, et elle a une documentation à part entière. Ce qui suit est simplement une explication d'un seul exemple.

Paramètres spécifiques à action

titles=Main%20Page

Le reste de l'URL d'exemple contient des paramètres utilisés par l'action « query ». Ici, nous demandons à l'API du service web des informations à propos de la page du Wiki appelée « Main Page ». (Le %20 est l'encodage de l'espace en encodage-pourcent) Si vous avez besoin de travailler avec plusieurs pages, vous pouvez les demander dans une seule et même requête pour optimiser les ressources serveur et réseau : titles=PageA|PageB|PageC. Voyez la documentation de query pour plus de détails.

prop=revisions

Vous pouvez vous enquérir de nombreux types d'informations, ou propiétés, à propos d'une page. Ce paramètre indique à l'API du service web que nous voulons des informations à propos d'une révision particulière de la page. Puisque nous ne fournissons aucune information sur la révision que nous cherchons, l'API va nous donner la dernière révision — la page principale de Wikipédia comme elle est actuellement.

rvprop=content

Enfin, ce paramètre indique à l'API du service web que nous voulons le contenu de la dernière révision de la page. Si nous avions donné rvprop=content|user à la place, nous aurions obtenu la dernière révision et le nom de l'utilisateur qui a fait la modification la plus récente.

Encore une fois, ceci est juste un exemple. Les requêtes query sont expliquées plus en profondeur ici, et la référence de l'API liste toutes les actions possibles; toutes les valeurs possibles pour rvprop, et tout les autres arguments.

Une introduction à l'API par Roan Kattouw au San Francisco Hackathon January 2012


Pour commencer

Avant d'utiliser l'API du service web de MediaWiki, lisez ces documents :

  • la FAQ ;
  • la page sur les formats d'entrée et de sortie ;
  • la page sur les erreurs et avertissements.
  • toute charte qui s'applique au wiki auquel vous souhaitez accéder, comme (pour les wikis de la fondation Wikimedia) nos conditions d'utilisation. Ces conditions vous sont applicables lorsque vous accédez au wiki ou l'éditez à travers l'API du service web, de la même façon que lorsque vous utilisez votre navigateur internet.

Après ceci, ce que vous devez lire dépend de ce que vous souhaitez faire. Le menu de droite propose des liens vers de la documentation détaillée, spécifique pour chaque tâche, où vous trouverez ci-dessous des indications plus générales.

Identification de votre client

Lorsque vous faites des requêtes HTTP à l'API du service web MediaWiki, assurez-vous d'indiquer un en-tête User-Agent qui identifie correctement votre client. N'utilisez pas la valeur par défaut User-Agent fournie par la bibliothèque cliente, mais créez un en-tête personnalisé qui identifie votre script ou votre service et fournit des moyens de vous contacter (par exemple, une adresse électronique).

Voici à quoi pourrait ressembler une chaîne User-Agent : 

MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) BasedOnSuperLib/1.4

Sur les wikis Wikimedia, si vous ne fournissez pas d'en-tête User-Agent, ou si vous en fournissez un vide ou un générique, vous requêtes échoueront avec une erreur HTTP 403 (cf. m:User-Agent policy). Les autres installations de MediaWiki peuvent avoir des politiques semblables.

Si vous appelez l'API à partir d'un JavaScript dans un navigateur, vous ne pourrez pas modifier l'en-tête User-Agent : le navigateur utilisera le sien. Pour contourner cela, utilisez l'en-tête Api-User-Agent : 

// Using XMLHttpRequest
xhr.setRequestHeader( 'Api-User-Agent', 'Example/1.0' );

// Using jQuery
$.ajax( {
    url: remoteUrlWithOrigin,
    data: queryData,
    dataType: 'json',
    type: 'POST',
    headers: { 'Api-User-Agent': 'Example/1.0' },
    success: function(data) {
       // do something with data
    }
} );

// Using mw.Api, specify it when creating the mw.Api object
var api = new mw.Api( {
    ajax: {
        headers: { 'Api-User-Agent': 'Example/1.0' }
    }
} );
api.get( {...} ).done(function(data) {
    // do something with data
});

// Using fetch
fetch( remoteUrlWithOrigin, {
    method: 'POST',
    headers: new Headers( {
        'Api-User-Agent': 'Example/1.0'
    } )
    // Other init settings such as 'credentials'
} ).then( function ( response ) {
    if ( response.ok ) {
        return response.json();
    }
    throw new Error( 'Network response was not ok: ' + response.statusText );
} ).then( function ( data ) {
    // do something with data
});

En PHP, vous pouvez identifier votre client avec un code tel que celui-ci : 

ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) BasedOnSuperLib/1.4');

Ou, si vous utilisez cURL : 

curl_setopt($curl, CURLOPT_USERAGENT, 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) BasedOnSuperLib/1.4');

Connexion

Votre client aura probablement besoin de se connecter à MediaWiki, peut-être avec son propre compte utilisateur. Voir la page de manuel de connexion pour de plus amples informations.

Bonnes pratiques de l'API

Veuillez également lire API:Etiquette

Si vos requêtes récupèrent des des données qui peuvent être mises en cache, vous devriez faire ce qu'il faut pour les mettre en cache afin de ne pas avoir à demander plusieurs fois les mêmes données. Vous pouvez trouver de plus amples informations sur la limitation des taux de transfert, les accès concurrents et les bonnes pratiques générales de l'API à la page API:Etiquette. Certains clients peuvent être capables de mettre eux-mêmes les données en caches, mais, pour d'autres (en particulier les clients JavaScript), ce n'est pas possible.

Conformément aux spécifications HTTP, les requêtes POST ne peuvent être cachées. Aussi, lorsque vous accédez à des données depuis l'API du service web, vous devriez utiliser des requêtes GET et non POST.

Veuillez également noter qu'une requête ne peut pas être servie à partir du cache à moins que l'URL ne soit exactement la même. Si vous faites une requête api.php?....titles=Foo|Bar|Hello et mettez le résultat en cache, alors une requête api.php?....titles=Hello|Bar|Hello|Foo ne passera pas par le cache — même si MediaWiki renvoie les mêmes données !

Vous devriez faire attention à la normalisation des URL que vous envoyez au service web MediaWiki afin que des saisies d'utilisateurs légèrement différentes ne vous fassent pas perdre de temps en requêtes HTTP inutiles. Vous pouvez normaliser une liste de titres de pages en supprimant les doublons et en triant les titres dans l'ordre alphabétique. Des techniques semblables fonctionnent pour d'autres types de données.

Liens utiles

La barre de menu sur la droite de cette page fournit des liens vers une documentation plus détaillée et plus spécifique. Voici quelques liens en relation avec toute l'API :

Archives

Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Main_page/fr&oldid=2826646"