Difference between revisions of "Wiki Technical Guide/API"

From EncyclopAtys

Jump to: navigation, search
m
m (→‎Action API - Intro)
Line 7: Line 7:
  
 
The query module has many submodules (called query modules), each with a different function. There are '''3 types of query modules''':
 
The query module has many submodules (called query modules), each with a different function. There are '''3 types of query modules''':
−
* [https://www.mediawiki.org/wiki/Special:MyLanguage/API:Meta Meta information] about the wiki and the logged-in user
+
* [https://www.mediawiki.org/wiki/Special:MyLanguage/API:Meta Meta information] about the wiki and the logged-in user (ex: <nowiki>action=query&meta=submodule</nowiki> or <nowiki>action=query&meta=submodule1|submodule2</nowiki>)
−
* [https://www.mediawiki.org/wiki/Special:MyLanguage/API:Properties Properties] of pages, including page revisions and content
+
* [https://www.mediawiki.org/wiki/Special:MyLanguage/API:Properties Properties] of pages, including page revisions and content (ex: action=query&titles=title1&'''prop=property1|property2''')
−
* [https://www.mediawiki.org/wiki/Special:MyLanguage/API:Lists Lists] of pages that match certain criteria (Most list queries return [https://www.mediawiki.org/wiki/API:Lists 10 items by default])
+
* [https://www.mediawiki.org/wiki/Special:MyLanguage/API:Lists Lists] of pages that match certain criteria (Most list queries return [https://www.mediawiki.org/wiki/API:Lists 10 items by default], ex: action=query&'''list=list1|list2''')
 
You should use multiple query modules together to get what you need in one request, e.g. '''prop=info|revisions&list=backlinks|embeddedin|allimages&meta=userinfo''' is a call to six modules in one request.  
 
You should use multiple query modules together to get what you need in one request, e.g. '''prop=info|revisions&list=backlinks|embeddedin|allimages&meta=userinfo''' is a call to six modules in one request.  
  

Revision as of 18:23, 26 June 2019


Important.png
Under Construction Panel.png !!!! WIP !!!! Under Construction Panel.png
There are currently still 81 articles in preparation in the category "WIP"
Article in preparation. Please let the author finish it before you modify it.
The last editing was from Amosys on 26.06.2019.

Action API - Intro

Source: https://www.mediawiki.org/wiki/API:Query#Introduction_and_guidelines

The action=query module allows you to get information about a wiki and the data stored in it, such as the wikitext of a particular page, the links and categories of a set of pages, or the token you need to change wiki content.

The query module has many submodules (called query modules), each with a different function. There are 3 types of query modules:

  • Meta information about the wiki and the logged-in user (ex: action=query&meta=submodule or action=query&meta=submodule1|submodule2)
  • Properties of pages, including page revisions and content (ex: action=query&titles=title1&prop=property1|property2)
  • Lists of pages that match certain criteria (Most list queries return 10 items by default, ex: action=query&list=list1|list2)

You should use multiple query modules together to get what you need in one request, e.g. prop=info|revisions&list=backlinks|embeddedin|allimages&meta=userinfo is a call to six modules in one request.

all property query modules work on a set of pages that you specify using either titles, pageids, revids, or generator parameters. Do not ask for one page at a time – this is very inefficient, and consumes lots of extra resources and bandwidth: request information about multiple pages by combining their titles or ids with the '|' pipe symbol: titles=PageA|PageB|PageC.

Use generator if you want to get data about a set of pages that would be the result of another API call. For ex, if you want to get data about pages in a certain category, instead of querying list=categorymembers and then querying again with pageids set to all the returned pages, you should combine the two API calls into one by specifying generator=categorymembers in place of the list parameter.

If you're querying Wikimedia wikis and requesting results as format=json (or php), then specify formatversion=2. The original result format was designed around XML; the new structure is easier to process (and defaults to utf8).

Action API - simple ex

http://en.wiki.ryzom.com/w/api.php?action=query&prop=revisions&rvprop=content&format=jsonfm&formatversion=2&titles=Main%20Page simply gets the wiki markup (content) of a page: fetch (action=query) the content (rvprop=content) of the most recent revision of Main Page (titles=Main%20Page) in JSON with whitespace to make it easier to read (format=jsonfm).

Action API - Specifying pages

  • By name using the titles parameter, e.g. titles=Foo|Bar|Main_Page
  • By page ID using the pageids parameter, e.g. pageids=123|456|75915
  • By revision ID using the revids parameter, e.g. revids=478198|54872|54894545
    • Most query modules will convert revision ID to the corresponding page ID. Only prop=revisions actually uses the revision ID itself.
  • Using a generator

Specifying titles through the query string (either through titles or pageids) is limited to 50 titles per query (or 500 for those with the apihighlimits right, usually bots and sysops).

https://www.mediawiki.org/wiki/API:FAQ

  • If you are trying to get information about a page, you probably will use a prop= submodule of action=query. Other query submodules return lists of pages and meta-information about the wiki. View the generated API help of all query submodules.

Action API - Title normalization

converts page titles to their canonical form (Cap, replacing _ with spaces, and changing namespace to the localized form defined for that wiki). Title normalization is done automatically, regardless of which query modules are used. However, any trailing line breaks in page titles (\n) will cause odd behavior and they should be stripped out first.

Missing and invalid titles: appear in the <pages> section, but they have the missing or invalid attribute set. In output formats that support numeric array keys (JSON and PHP serialized), missing and invalid titles will have unique, negative page IDs. Query modules will just ignore missing or invalid titles, as they can't do anything useful with them. The titles in the Special: and Media: namespaces cannot be queried.

Resolving redirects

when the page has a redir, contain from and to attributes and may contain a tofragment attribute for those redirects that point to specific sections.

Continuing queries

there are more data matching the query, the API result includes a continue element. If you want further data, you would add its values (in the example, continue=-|| and accontinue=List_of_19th_century_baseball_players) to the original request to get the next set of results. You continue to do this until an API result does not have a continue element, indicating there are no more data matching the query.

Getting a list of page IDs

When not using the new JSON formatversion=2, the result page set in JSON is returned as an object keyed by page ID which can be difficult to properly iterate over in JavaScript. The indexpageids parameter returns these page IDs as an array for easier iteration. Note that the ordering of these page IDs still does not necessarily correspond to the ordering of the input (whether directly or via a generator)

https://en.wikipedia.org/w/api.php?action=query&titles=Main%20Page%7CFksdlfsdss%7CTalk:&indexpageids=&format=jsonfm

Page export

If the export parameter is set, an XML dump of all pages in the <pages> element will be added to the result - it only gives a result when used with specified titles (Generator, titles, pageids or revid). If the exportnowrap parameter is also set, only the XML dump (not wrapped in an API result) will be returned.

Generators: use the output of a list instead of the titles

Other query modules will treat generated pages as if they were given in a parameter. Only one generator is allowed.

see lists

Lists

https://www.mediawiki.org/wiki/API:Lists

Lists generally return aggregations of data, such as pages gathered from across a wiki, or links gathered within a single page. To request a list, pass the list parameter of your query string a valid list submodule, such as allimages or usercontribs.

To use the list API, specify action=query&list=list1|list2 in the URL.

Ex list=allcategories https://www.mediawiki.org/wiki/API:Allcategories

Parameters

acfrom The category to start enumerating from. accontinue When more results are available, use this to continue. acto The category to stop enumerating at.
acprefix Search for all category titles that begin with this value. acdir Direction to sort in. One of the following values: ascending, descending Default: ascending
acmin Only return categories with at least this many members. Type: integer acmax Only return categories with at most this many members. Type: integer
aclimit How many categories to return. No more than 500 (5,000 for bots) allowed. Type: integer or max Default: 10 acprop Which properties to get:

  • size Adds number of pages in the category.
  • hidden Tags categories that are hidden with __HIDDENCAT__. Values (separate with | or alternative): size, hidden Default: (empty)

Ex:

examples

Ex to list pages that belong to a given category list=categorymembers. https://www.mediawiki.org/wiki/API:Categorymembers

Links

https://www.mediawiki.org/wiki/API:FAQ/fr


Retrieved from "https://en.wiki.ryzom.com/w/index.php?title=Wiki_Technical_Guide/API&oldid=30306"