API:Tutoriel

This page is a translated version of the page API:Tutorial and the translation is 74% complete.

Dans ce tutoriel, vous découvrirez ce qu'est l' API Action de MediaWiki, comment l'utiliser, le format des requêtes, une requête simple et des exemples de projets qui utilisent l'API Action.

Aperçu de l'API Action de MediaWiki

L' API Action de MediaWiki est un service web utilisant REST et qui permet aux utilisateurs de réaliser certaines actions sur les wikis telles que la création de page, l'authentification, l'analyse syntaxique, la recherche, etc. API:Page principale est un bon point d'entrée pour comprendre l'API.

Votre programme envoie des requêtes à l'API pour avoir accès aux fonctionnalités du wiki. Par exemple se connecter à un wiki, créer ou modifier une page, rechercher un titre, chercher une texte dans le contenu, ou analyser un contenu. L'API Action est disponible pour les développeurs tiers, les développeurs d'extensions Wikimedia, et les administrateurs de site.

Dans la barre latérale droite de cette page il existe plusieurs fonctions réalisées par l'API et groupées par catégorie. Before sending requests to a wiki server, first read through the overview pages such as data formats, errors and warnings, and the Action API FAQ.

Comment utiliser l'API Action de MediaWiki

You can request for data from client side to the server over HTTP and get the response back in a standard format (typically JSON). Une requête est constituée d'un point d'accès et d'une série de paramètres. Vous pouvez utiliser deux types de requêtes : GET et POST. Dans une requête GET, un paramètre contient la chaîne de caractères de la requête dans l'URL. Dans les requêtes POST, mettez les paramètres au format JSON.

Format de la requête

All Wikimedia Wikis have endpoints in this format http://example.org/w/api.php. To operate on the MediaWiki main site or English Wikipedia, use the related endpoint. For example, the English Wikipedia is at https://en.wikipedia.org/w/api.php For testing new accounts or test edits to pages, use the test wiki endpoint https://test.wikipedia.org/w/api.php.

In the query string in the URL, add the action parameter. It tells the API which action to perform. The most popular action is query (the URL would contain action=query), which allows fetching data from a wiki. Following the action parameter, add another parameter to indicate which one of the three query module types you want to perform:

  • prop - obtenir les propriétés des pages  
  • list - obtenir la liste des pages qui vérifient un certain critère
  • meta - obtenir les méta informations concernant le wiki et les utilisateurs

Finally, include the format parameter, which tells the API in which format to get the results. The recommended format is JSON. The API has supported other output formats in the past, but they are not generally recommended.

 
Request format

Une requête simple

Let’s take an example of a simple query to understand what a typical GET request and response would look like in the context of the Action API.

Essayons de chercher un titre dans un wiki. Nous utiliserons le module search documenté sur API:Search/fr .

Requête GET

Pour rechercher des titres de pages ou du contenu qui avec Craig Noone, l'URL de la requête HTTP GET sera :

Explication de chaque partie de l'URL :

  • http://en.wikipedia.org/w/api.php est le point d'accès principal. Dans ce cas il s'agit de la Wikipedia anglophone.
  • action=query signifie rechercher les données dans le wiki.
  • list=search signifie obtenir la liste des pages qui vérifient un critère.
  • srsearch=Craig%20Noone indique le titre la page ou le contenu à rechercher. Le %20 représente un caractère espace dans une URL.
  • format=json indique la sortie en JSON, qui est le format de sortie recommandé.

Réponse

La réponse est un document au format JSON avec une liste de titres des pages qui correspondent à Craig Noone :

{
    "batchcomplete": "",
    "continue": {
        "sroffset": 10,
        "continue": "-||"
    },
    "query": {
        "searchinfo": {
            "totalhits": 210
        },
        "search": [
            {
                "ns": 0,
                "title": "Craig Noone",
                "pageid": 18846922,
                "size": 22548,
                "wordcount": 1771,
                "snippet": "<span class=\"searchmatch\">Craig</span> Stephen <span class=\"searchmatch\">Noone</span> (born 17 November 1987) is an English professional footballer who plays as a winger for Bolton Wanderers. Born in Kirkby, he has also",
                "timestamp": "2018-11-02T22:25:45Z"
            },
            {
                "ns": 0,
                "title": "Noone",
                "pageid": 32906333,
                "size": 553,
                "wordcount": 64,
                "snippet": "<span class=\"searchmatch\">Noone</span> is a surname that may refer to:  <span class=\"searchmatch\">Craig</span> <span class=\"searchmatch\">Noone</span> (born 1987), English football midfielder Jimmie <span class=\"searchmatch\">Noone</span> (1895–1944), American jazz clarinetist Kathleen",
                "timestamp": "2015-08-16T05:16:17Z"
            }
            ...
        ]
    }
}


Exemples de projets qui utilisent l'API Action

Exemples de projets de Wikimedia qui utilisent l'API Action :

  • Wikipedia iOS App, in which one of the features is to search for wiki pages near your location.
  • Robots qui opèrent sur un wiki. Pywikibot est un environnement pour les robots, écrit en Python, et qui s'interface avec l'API MediaWiki utilisée par beaucoup de développeurs de robots.
  • API use in visualizing data obtained from a wiki. Such as this neat visualization that shows real time edits made on Wikipedia.

Notes supplémentaires

  • Several sites are using MediaWiki. They might all be running a different version of MediaWiki and in turn the API. Some module parameters supported in one version might be deprecated or removed in others. You could learn about that in each module's documentation via API help module.
  • If you want to make a lot of API calls, and perhaps run very busy and active bots, talk to wiki admins ahead of time, so they do not block you. See list of Administrators of Wikimedia projects. Read more about this topic on API:Etiquette .
  • All data modifying actions such as logging, editing or moving a page, and watching or patrolling changes would require tokens. You would need to obtain tokens via API:Tokens/fr to proceed further.

Ressources