Aller au contenu

Utilisateur:Klymandre/Mémo API

Une page de Wikipédia, l'encyclopédie libre.
Retour page principale

Mémo API (Catégories)

Quelques liens

[modifier | modifier le code]

Pour accéder à une page quelconque concernant l'API (de l'aide an anglais, le plus souvent), il suffit de se rendre sur https://www.mediawiki.org, et taper "api:" dans la zone de recherche en haut à droite.

Si on se rend sur https://fr.wikipedia.org/w/api.phpsans paramètre, on se retrouve sur l'aide à l'utilisation des paramètres possibles, en français. C'est une redirection de l'URL plus complète : https://fr.wikipedia.org/w/api.php?action=help

Fonctionnement général

[modifier | modifier le code]

L'API Wikipédia se résume à une URL qui commence par https://fr.wikipedia.org/w/api.php

Ensuite, viennent les paramètres. C'est à dire qu'après api.php, il va y avoir un "?", et différents paramètres séparés par le signe "&". (Longueur maximum totale : 8'100 caractères, il y a donc de la marge !)

Exemple : https://fr.wikipedia.org/w/api.php?action=query&list=allpages

Cette URL dynamique va renvoyer les 10 premiers articles de Wikipédia, triés par ordre alphabétique.

Dans cet exemple, le premier paramètre "action" est défini sur "query", et ce sera le cas pour la totalité des données extraites de Wikipédia. Quasiment aucune autre action n'est possible pour les utilisateurs Lambda pour des raisons de sécurité, et d'éviter de transformer les données de Wikipédia sans contrôle. On peut par exemple, supprimer des pages, les renommer, voire même bloquer un utilisateur, mais tant qu'on n'est pas au moins Administrateur, un message d'erreur résultera d'une tentative d'exécution de ce genre de requête.

Le deuxième paramètre ("list") représente le type de données à renvoyer. En l'occurrence, des articles, mais nous verrons qu'il peut s'agit d'autres choses, comme des catégories.

Certains paramètres sont définis par défaut, comme par exemple format=jsonfm. Ainsi "api.php?action=query&flist=allpages" est équivalent à "api.php?action=query&format=jsonfm&list=allpages". Jsonfm est le format d'affichage des résultats.

On voit ainsi qu'il est nécessaire de connaître les différents paramètres, ainsi que leur valeurs possibles. Afin de se familiariser et tester les différents paramètres, il y a un bac à sable spécial API ici : Spécial:APISandbox.

Bac à sable API

[modifier | modifier le code]

Hello, World !

[modifier | modifier le code]

Comme premier exercice, nous allons récupérer les 10 premiers articles (par ordre alphabétique) de Wikipédia.

Allez dans le bac à sable API : Spécial:ApiSandbox. Vous arrivez devant une page surmontée de 3 boutons: "Développer le panneau", "Faire la demande", "Effacer" A gauche, c'est écrit :

  • main
    • format=json

A droite, un peu plus bas, vous avez une liste déroulante titrée "Action". Cliquez dessus. Cherchez "query" et sélectionnez-le .

A cet instant, la colonne de gauche s'actualise :

  • main
    • action=query
    • format=json

Cliquez sur cette nouvelle rubrique de gauche action=query. Ca actualise le contenu de droite (qui est alors titré : "action=query")

Un peu plus bas, il y a une zone "prop", et plus bas encore : "list". Cliquez sur cette liste déroulante "list", et choisissez "allpages". Dès que vous avez fait ça, la liste de gauche se complète encore, et devient :

  • main
    • action=query
      • list=allpages
    • format=json

Voilà : il ne reste plus qu'à cliquer sur le bouton en haut : "Faire la demande".

A cet instant, la colonne de gauche s'actualise en ajoutant la rubrique "Résultats", comme ceci :

  • main
    • action=query
      • list=allpages
    • format=json
  • Résultats

Le résultat s'affiche en même temps : 

{
    "batchcomplete": "",
    "continue": {
        "apcontinue": "!_(album)",
        "continue": "-||"
    },
    "query": {
        "allpages": [
            {
                "pageid": 222657,
                "ns": 0,
                "title": "!" 
etc...

Et l'URL est actualisée pour ressembler à ceci :https://fr.wikipedia.org/wiki/Sp%C3%A9cial:ApiSandbox#action=query&format=json&prop=&list=allpages&meta=

Attention : si vous cliquez dessus, vous devrez cliquer sur "Faire la demande" pour obtenir le résultat.

De tout ce qui est encadré de gris juste ici au dessus, il faut surtout retenir que le premier article Wikipédia trié par ordre alphabétique se nomme sobrement "!" (point d'exclamation, simplement)

Les 10 premiers articles sont : "!", "!!", "!!!", "!?", "!K7", "!Karas", "!Kung", "!T.O.O.H.!", "!WOWOW!" et "!  !". Cette page vous confirmera la justesse du résultat.

Transposition de l'API dans le bac à sable en réelle interrogation

[modifier | modifier le code]

L'exemple que je viens de vous montrer renvoie cette URL : 

https://fr.wikipedia.org/wiki/Sp%C3%A9cial:ApiSandbox#action=query&format=json&prop=&list=allpages

Le paramètre "prop=" est vide, et on peut donc aisément s'en passer.

Afin de visualiser ce même résultat en contexte "normal", c'est à dire en dehors du bac à sable API, il suffit de recopier toute la partie de droite, à partir de "action", et de la mettre après "api.php?", comme ceci : 

https://fr.wikipedia.org/w/api.php?action=query&format=json&list=allpages

Attention : bien que le résultat soit techniquement le même, il ne sera pas aussi lisible car il ne sera pas aimablement indenté sous forme de paragraphes comme on l'a vu plus haut dans le bac à sable, mais se présentera comme ceci : 

{"batchcomplete":"","continue":{"apcontinue":"!_(album)","continue":"-||"},"query":{"allpages":[{"pageid":222657,"ns":0,"title":"!"},{"pageid":4433171,"ns":0,"title":"!!"},{"pageid":351979,"ns":0,"title":"!!!"},{"pageid":5142538,"ns":0,"title":"!?"},{"pageid":7081204,"ns":0,"title":"!K7"},{"pageid":997109,"ns":0,"title":"!Karas"},{"pageid":7376451,"ns":0,"title":"!Kung"},{"pageid":6892939,"ns":0,"title":"!T.O.O.H.!"},{"pageid":9125021,"ns":0,"title":"!WOWOW!"},{"pageid":4452220,"ns":0,"title":"! !"}]}}

Affichage en format XML

[modifier | modifier le code]

On peut toutefois améliorer les choses en demandant un affichage en format xml, car c'est mon navigateur lui-même qui va alors me proposer un affichage convivial :

https://fr.wikipedia.org/w/api.php?action=query&format=xml&list=allpages& 

<api batchcomplete="">
  <continue apcontinue="!_(album)" continue="-||"/>
  <query>
    <allpages>
      <p pageid="222657" ns="0" title="!"/>
      <p pageid="4433171" ns="0" title="!!"/>
      <p pageid="351979" ns="0" title="!!!"/>
      <p pageid="5142538" ns="0" title="!?"/>
etc...

On peut demander le format XML dans le bac à sable également. Retournez dans le bac à Sable, ou cliquez ici pour vous retrouver dans le bac à sable avec nos critères précédents (action=query&list=allpages).

Dans la colonne de gauche, cliquez sur "main", et dans la colonne de droite, format : choisissez XML.

Attention :Si vous cliquez ensuite dans la colonne de gauche sur "Résultats", vous reverrez l'ancien résultat, donc pas en format XML. Pour qu'il actualise, vous devez cliquer en haut sur le bouton "Faire la demande"

ça donne ceci : 

<?xml version="1.0"?>
<api batchcomplete="">
  <continue apcontinue="!_(album)" continue="-||" />
  <query>
    <allpages>
      <p pageid="222657" ns="0" title="!" />
      <p pageid="4433171" ns="0" title="!!" />
      <p pageid="351979" ns="0" title="!!!" />
      ...
      <p pageid="4452220" ns="0" title="! !" />
    </allpages>
  </query>
 </api>

RequestID

[modifier | modifier le code]

Il est possible d'ajouter un paramètre personnel "RequestID" qui va contenit la variable de mon choix, dans un but personnel, comme ceci : 

https://fr.wikipedia.org/w/api.php?action=query&format=xml&list=allpages&requestid=Salut%20%C3%A0%20tous

Qui donne : 

<api batchcomplete="" requestid="salut à tous">
  <continue apcontinue="!_(album)" continue="-||"/>
    <query>
      <allpages>
        <p pageid="222657" ns="0" title="!"/>
        <p pageid="4433171" ns="0" title="!!"/>
etc.

Affichage de pages en HTML

[modifier | modifier le code]

action=render

[modifier | modifier le code]

Ce lien : 

https://fr.wikipedia.org/wiki/Luc Lafnet?action=render

renverra la version pur HTML allégé de toutes les fioritures de cette page : 

https://fr.wikipedia.org/wiki/Luc Lafnet

action=parse

[modifier | modifier le code]

Cette deuxième méthode permet de voir le format HTML en format JSON (ou xml si on le précise) 

https://fr.wikipedia.org/w/api.php?action=parse&page=Luc_Lafnet
https://fr.wikipedia.org/w/api.php?action=parse&page=Luc_Lafnet&format=xml

Paraminfo

[modifier | modifier le code]

Il est possible de créer une requête API qui renvoie tous les paramètres d'un mot-clé. Par exemple, j'aimerais connaître le détail des paramètres possibles (Nom du paramètre, type de données et listes de choix possibles) pour le sous paramètre AllPages du paramètre principal Query.

  1. Allez dans le bac à sable API
  2. main  : action : choisir "paraminfo"
  3. cliquer à gauche sur action=paraminfo
  4. Modules : écrire : query allpages
  5. Cliquer sur "Faire la demande"
  6. Alternative à tout ça : cliquer directement ici.

Voici un extrait du résultat : 

...
"https://www.mediawiki.org/wiki/API:Allpages"
                ],
                "parameters": [
                    {
                        "name": "from",
                        "type": "string"
                    },
                    {
                        "name": "continue",
                        "type": "string"
                    },
...

Maintenant, si dans le bac à sable API :

  • Vous remplacez dans le main : action : query
  • Cliquez sur e paramètre Action = query
  • A droite, dans List, écrivez allpages
  • Cliquez maintenant à gauche sur List=allpages

Vous aurez alors, à droite, les paramètres que j'ai écrit plus haut avec l'action paraminfo, avec pour seule nuance que les paramètres seront tous précédés de ap (from devient apfrom - ap : allpages)Pareil pour "continue" et en fait pour tous les autres paramètres de allpages.

Quelques exemples de requêtes intéressantes

[modifier | modifier le code]

Listing d'articles

[modifier | modifier le code]

Pour obtenir la liste des premiers articles Wikipédia par ordre alphabétique :

Deux paramètres seulement sont nécessaires : action=query, et list=allpages 

https://fr.wikipedia.org/w/api.php?action=query&list=allpages

Qui va nous renvoyer ce résultat (Je montre les deux premiers articles, respectivement nommés "!" et "!!", mais 10 (valeur par défaut) sont réellement affichés. Le format utilisé est "JSONFM", qui est une représntation du format JSON "à la sauce HTML" afin que le résultat soit plus facilement lisible : 

{
    "batchcomplete": "",
    "continue": {
        "apcontinue": "!_(album)",
        "continue": "-||"
    },
    "query": {
        "allpages": [
            {
                "pageid": 222657,
                "ns": 0,
                "title": "!"
            },
            {
                "pageid": 4433171,
                "ns": 0,
                "title": "!!"
            },
etc...

la ligne : "apcontinue": "!_(album)", donne le nom du 11ème article, soit celui qui se trouve juste après la fin de la requête.

Voici le même résultat, mais en format XML. La casse est importante, et xml doit être écrit en minuscule. si on écrit format=XML, la requête renvoie juste une erreur. 

https://fr.wikipedia.org/w/api.php?action=query&list=allpages&format=xml

<api batchcomplete="">
  <continue apcontinue="!_(album)" continue="-||"/>
    <query>
      <allpages>
        <p pageid="222657" ns="0" title="!"/>
        <p pageid="4433171" ns="0" title="!!"/>
        <p pageid="351979" ns="0" title="!!!"/>
        <p pageid="5142538" ns="0" title="!?"/>
etc...

Nous pouvons changer le nombre de résultats, et préciser jusqu'à un maximum de 500 résultats avec aplimit=500. Si on demande plus que 500, il renvoie les 500 premiers. Et s'il y a moins de 500 résultats, il en affiche évidemment moins, comme ceci : 

https://fr.wikipedia.org/w/api.php?action=query&format=xml&list=allpages&aplimit=500

On peut également écrire : aplimit=max 

<api batchcomplete="">
  <continue apcontinue="(10123)_Fideöja" continue="-||"/>
    <query>
      <allpages>
        <p pageid="222657" ns="0" title="!"/>
        <p pageid="4433171" ns="0" title="!!"/>
... (496 autres pages intermédiaires)
        <p pageid="9548236" ns="0" title="(10122) Froding"/>
        <p pageid="9524182" ns="0" title="(10122) Fröding"/>
      </allpages>
    </query>
</api>

Si je désire toujours voir les 500 premiers articles, mais dont le titre doit commencer par "aaaa", j'ajoute le paramètre apprefix=aaaa, comme ceci : 

https://fr.wikipedia.org/w/api.php?action=query&format=xml&apprefix=aaaa&list=allpages&aplimit=500

Je peux le mettre ou je veux, cette URL donne le même résultat : 

https://fr.wikipedia.org/w/api.php?action=query&format=xml&list=allpages&aplimit=500&apprefix=aaaa

<p pageid="6559030" ns="0" title="Aaaaa!"/>
<p pageid="5987187" ns="0" title="AaaaaAAaaaAAAaaAAAAaAAAAA"/>
<p pageid="5987186" ns="0" title="AaaaaAAaaaAAAaaAAAAaAAAAA!!!"/>
<p pageid="4405824" ns="0" title="AaaaaAAaaaAAAaaAAAAaAAAAA!!! -- A Reckless Disregard for Gravity"/>
<p pageid="4398149" ns="0" title="AaaaaAAaaaAAAaaAAAAaAAAAA!!! - A Reckless Disregard for Gravity"/>
<p pageid="9487820" ns="0" title="AaaaaAAaaaAAAaaAAAAaAAAAA!!! A Reckless Disregard for Gravity"/>

Pour le même résultat , mais sur Wikipédia en anglais, il suffit de remplacer "fr.wikipedia.org" par "en.wikipedia.org" : 

https://en.wikipedia.org/w/api.php?action=query&format=xml&list=allpages&aplimit=500&apprefix=aaaa

<p pageid="3668464" ns="0" title="Aaaa"/>
<p pageid="7047241" ns="0" title="Aaaa battery"/>
<p pageid="47275646" ns="0" title="Aaaaa"/>
etc... (il y a plus de pages en anglais qu'en français)

La même chose mais sur Wikipédia en anglais : https://en.wikipedia.org/w/api.php?action=query&generator=allpages&format=xml&gaplimit=500
Ce document provient de « https://fr.wikipedia.org/w/index.php?title=Utilisateur:Klymandre/Mémo_API&oldid=126026577 ».