API:Data formats/fr

Entrées
L'API récupère ses entrées à partir des paramètres fournis dans la requête ou à partir d'une entité POST dans le format application/x-www-form-urlencoded ou multipart/form-data. Chaque module (et chaque sous-module ) a sa propre liste de paramètres, qui sont listés dans la documentation et dans action=help. Ils peuvent également être récupérés par.

Encodage
Toute entrée doit être du UTF-8 valide, sous la forme NFC. MediaWiki essayera de convertir les autres formats ce qui pourra éventuellement générer des erreurs.

Paramètres multi-valeurs
Certains paramètres acceptent plusieurs valeurs séparées par une barre verticale   (pipe). Par exemple, pour soumettre les trois valeurs,   et   pour le paramètre  , vous devez écrire    dans la requête. Si un paramètre accepte de multiples valeurs, cela est affiché explicitement par  et. La documentation ne fait pas la différence directement entre les paramètres multi-valeurs mais la description de ces paramètres suit habituellement les mots "Une liste de ..." ou "Une liste de ... séparés par des barres verticales".

Si vous avez besoin de soumettre une liste de valeurs parmi lesquelles certaines contiennent un caractère barre verticale (ce qui est rare - la plupart des paramètres multi-valeurs sont des listes de titres de pages, ou des noms d'utilisateurs, dont aucun ne peut contenir de barres verticales), vous pouvez utiliser le caractère de séparateur unitaire à la place:   (où  représente U+001F) va soumettre les trois valeurs ,   et. (Remarquez qu'il y a un caractère  supplémentaire au début. Ceci est obligatoire pour éviter l'ambiguité avec le cas où on soumet une valeur unique contenant une barre verticale).

Valeurs booléennes
Les paramètres booléens fonctionnent comme des cases à cocher HTML : si le pramètre est spécifié dans la requête HTTP, quelle que soit sa valeur, il est considéré à vrai. Pour une valeur à faux, ne pas fournir le paramètre entièrement. La meilleure manière de spécifier une valeur à vrai dans une requête HTTP est d'utiliser ; ce qui suit le   assure que l'explorateur où la bibliothèque HTTP ne supprimera pas le "vide" de unParam.

Horodatages
Les paramètres qui contiennent des valeurs de références horaires (horodatage), acceptent des valeurs de temps sous différents formats :


 * format ISO 8601:
 * Format de l'horodatage interne MySQL:
 * Format de l'horodatage UNIX  (nombre de secondes depuis le 1er janvier 1970)
 * Format de l'horodatage UNIX  (nombre de secondes depuis le 1er janvier 1970)

Dans les sorties, les horodatages sont toujours au format ISO 8601.

Sortie
L'API MediaWiki a historiquement pris en charge un nombre de différents formats, mais ceci a compliqué les développements successifs. Nous aimerions standardiser en adoptant un seul format JSON. Pour l'instant, MediaWiki ne recommande pas, mais prend encore en charge deux formats de sortie génériques supplémentaires (XML et PHP). Vous devez toujours spécifier le format à l'aide du paramètre d'entrée (de la requête)  suivi d'une valeur en minuscules. Les modules de flux tels que les modifications récentes de flux réécrasent le format de sortie standard, au lieu d'utiliser RSS ou Atom, comme spécifié par leur paramètre. Dans ces cas, le format spécifié par le paramètre  n'est utilisé que s'il y a une erreur. Tous les formats autres que JSON sont obsolètes. XML et PHP sont encore pris en charge, mais tous les autres ont été supprimés dans MediaWiki 1.26 et 1.27; voi le tableau ci-dessous. Tous les nouveaux utilisateurs de l'API doivent utiliser JSON. Les clients écrits en PHP doivent éviter d'utiliser le format PHP parce qu'il n'est pas sécurisé. Il est maintenu jusqu'à présent simplement à cause de sa popularité.

Tous les modules permettent d'utiliser n'importe quel format générique pour les informations de sortie - sauf indication contraire. Pour simplifier le débogage, tous les formats génériques possèdent l'option "mise en forme HTML améliorée pour l'impression" avec le suffixe.

Le format par défaut a changé en MediaWiki 1.25 vers ; dans les versions précédentes de MediaWiki, c'était.

Remarquez que, alors que les formats d'impression améliorée sont tous indentés et séparent les éléments syntaxiques avec des retours à la ligne, les formats non-améliorés ne font pas cela.

Il existe beaucoup de bibliothèques de conversion et de convertisseurs en ligne pour transformer les réponses JSON en d'autres formats; par exemple, JSON-CSV convertit en liste de valeurs séparées par des virgules

Paramètres JSON
et  acceptent les paramètres supplémentaires suivants :


 * Précisez  pour obtenir que json (et php) formatent les réponses dans un format plus propre. Ceci encode aussi la plupart des caractères non-ASCII en UTF-8.
 * Précisez  pour obtenir que json (et php) formatent les réponses dans un format plus propre. Ceci encode aussi la plupart des caractères non-ASCII en UTF-8.
 * Précisez  pour obtenir que json (et php) formatent les réponses dans un format plus propre. Ceci encode aussi la plupart des caractères non-ASCII en UTF-8.

Restrictions pour les callback
Si vous utilisez JSON en mode callback, certains éléments sont désactivés par sécurité :


 * Les jetons ne peuvent pas être obtenus (donc les actions de modification d'état ne sont pas possibles)
 * Le client est traité comme un utilisateur anonyme (c'est à dire non connecté) pour tous les sujets, même après s'être connecté via
 * Cela signifie que les éléments qui nécessitent des droits additionnels, tels que, ne fonctionneront pas à moins que les utlisateurs anonymes soient autorisés à les utiliser

Exemples
il peut être utile d'ajouter le paramètre '&indexpageids' pour analyser le code JSON si l'ID de la page ("736") n'est pas connu avant le résultat.