API: Difference between revisions

Add links
From Meta, a Wikimedia project coordination wiki
Browse history interactively
← Older edit
Content deleted Content added
VisualWikitext
Revert to the revision prior to revision 22874674 dated 2022-02-22 05:23:35 by Ogmommy3 using popups
Tag: Manual revert
 
(106 intermediate revisions by 24 users not shown)
Line 1: Line 1:
{{MovedToMediaWiki|API}}
<div style="background: #f0f0e0; border: 2px solid #aaa; margin: 1em 10%; padding: 4px 4px 4px 15px; width:60%; text-align: center;">
'''Attention visitors'''


Moved preserving full histories. '''[[User:Robchurch|robchurch]]''' | [[User_talk:Robchurch|talk]] 07:09, 14 May 2007 (UTC)
This page discusses the future API for MediaWiki software.

<div style="text-align: left;">
MediaWiki at present has three interfaces:
* [http://en.wikipedia.org/w/query.php Query API] for retrieving any information in xml/json/php formats.
* [[Special:Export]] feature (bulk export of xml formatted data)
* Regular Web-based interface
</div>
</div>

== Implementation Strategy ==
=== File/Module Structure ===
* api.php is the entry point, located at the root of the mediawiki
* includes/api will contain all files related to the api, but none of them will be allowed as entry points
** files related to formatting the output will be in the form ''Output*.php'',

=== Internal Data Structures ===
* Query API has had very successful structure of one global nested array() structure passed around. Various modules would add pieces of data to many different points of that array, until, finally, it would get rendered for the client by one of the printers (output modules). For the API, I suggest wrapping this array as a class with helper functions to append individual leaf nodes.

=== Error/Status Reporting ===
For now we decided to include error information inside the same structured output as normal result (option #2).

For the result, we may either use the standard HTTP error codes, or always return a properly formatted data:

; Using HTTP code
void header( string reason_phrase [, bool replace [, int http_response_code]] )
The ''header()'' can be used to set the return status of the operation. We can define all possible values of the reason_phrase, so for the failed login we may return code=403 and phrase="BadPassword", whereas for any success we would simply return the response without altering the header.

''Pros'': Its a standard. The client always has to deal with http errors, so using http code for result would remove any separate error handling the client would have to perform. Since the client may request data in multiple formats, an invalid format parameter would still be properly handled, as it will simply be another http error code.

''Cons'': ...

; Include error information inside a proper response
This method would always return a properly formatted response object, but the error status / description will be the only values inside that object. This is similar to the way current Query API returns status codes.

''Pros'': HTTP error codes are used only for the networking issues, not for the data (logical errors). We do not tied to the existing HTTP error codes.

''Cons'': If the data format parameter is not properly specified, what is the format of the output data? Application has to parse the object to know of an error (perf?). Error checking code will have to be on both the connection and data parsing levels.

== Sample Requests ==
=== Login ===
'''Request:'''
api.php ? action=login & name=Yurik & password=12345 [& domain=wikipedia.org]
'''Result:'''
api:
login:
result: Success ''Other values: NoName, Illegal, WrongPluginPass,''
''NotExists, WrongPass, EmptyPass''
token: 1234567890ABCDEF ''Also returned as a cookie (i.e. enwikiToken)''
userName: Yurik ''Also returned as a cookie (i.e. enwikiUserName)''
userID: 12345 ''Also returned as a cookie (i.e. enwikiUserID)''

=== Query ===
==== General ====
===== Title Normalization =====
: Converts improper page titles to their proper form. Capitalizes first character, replaces '_' with ' ', changes canonical namespace names to their localized alternatives, etc.
'''Request:''' ''Note: articleA's first letter is not capitalized''
api.php ? action=query & titles=Project:articleA|ArticleB
'''Result:'''
api:
query:
pages:
Wikipedia:ArticleA: ''Project: is converted to Wikipedia: when running on en-wiki.''
ns: 4 ''Show title's namespace except when ns=0''
ArticleB:
badtitles: ''This element needs a better name''
Project:articleA: Wikipedia:ArticleA

===== Redirects =====
: Redirects can be resolved by the server, so that the target of redirect is returned instead of the given title. This example is not very usefull without additional what=... element, but shows the usage of redirect function. The 'redirects' section will contain the target of redirect and non-zero namespace code. Both normalization and redirection may take place. In case of redirect to a redirect, all redirections will be solved, and in case of a circular redirection, there might not be a page in the 'pages' section.
'''Request:'''
api.php ? action=query & titles=Main page & redirects
'''Result:'''
api:
query:
pages:
Main Page:
redirects:
Main page: Main Page

===== Circular Redirects =====
: Assume Page1 &rarr; Page2 &rarr; Page3 &rarr; Page1 (circular redirect). Also, in this example a non-normalized name 'page1' is used.
'''Request:'''
api.php ? action=query & titles=page1 & redirects
'''Result:'''
api:
query:
redirects:
Page1: Page2 ''Redirects are present, but not the 'pages' element.''
Page2: Page3
Page3: Page1
badtitles:
page1: Page1

==== Page Information ====
Page information items are used to get various data about a list of pages provided with the ''titles='' parameter. Content, links, interwiki links, and other information may be obtained.

===== categories (cl) =====
: Gets a list of all templates used on the provided pages. Limit: 200/1000.
: Parameters: extrainfo (adds sortkey & timestamp).

===== content (??) =====
: Returns wiki markup for the given list of articles. Requesting content is just a shorthand for the last revision request with content, so it would be equivalent to what=revisions & rvprop=content without any other rv* parameters. Limit: No more than 50 (user) / 200 (bot) page contents per request.
'''Request:'''
api.php ? action=query & what=content & titles=ArticleA|ArticleB
'''Result:'''
api:
query:
pages:
ArticleA:
id: 12345
lastrev: 67890
revisions:
67890:
content: ...raw page content...
ArticleB:
id: 0 '' ID=0 when title does not exist

===== langlinks (ll) =====
: Gets a list of all language links (interwikies) from the provided pages to other languages. Limit: 200/1000.

===== links (pl) =====
: Gets a list of all links from the provided pages. Limit: 200/1000.
: Parameters: namespace (flt).

===== templates (tl) =====
: Gets a list of all templates used on the provided pages. Limit: 200/1000.

==== Revisions ====
: Returns revisions for a given article based on the selection criteria. Revisions may be used with multiple titles only when working with the latest revision. When using rvlimit, rvdir=newer, rvstart, or rvend parameters, titles= must have only one title listed. By default, revisions shows only the id of the last revision.
'''Request:'''
api.php ? action=query & what=revisions & titles=ArticleA & rvprop=timestamp|user|comment|content
'''Result:'''
api:
query:
pages:
ArticleA:
id: 12345
lastrev: 67890
revisions:
67890:
timestamp: 20060908025739
user: UserX
comment: ...change comment...
content: ...raw revision content...

; Additional 'revisions' samples
: Get the timestamps of up to 10 revisions, begining at 2006-09-01 and moving forward in time.
api.php ? action=query & what=revisions & titles=ArticleA & rvprop=timestamp & rvlimit=10 & rvdir=newer & rvstart=20060901000000
: Get the timestamps of all revisions for the entire month of September 2006. rvlimit is optional. If the number of revisions exceeds the limit, the 'revisions' element will contain ''' 'continue':'rvstart=20060920122343' ''' with the timestamp to continue from.
api.php ? action=query & what=revisions & titles=ArticleA & rvprop=timestamp & rvstart=20060901000000 & rvend=20061001000000
: Get the timestamps of up to 10 revisions, begining at 12345 and moving back in time. If more than 10 revisions are available, 'revisions' element will contain ''' 'continue':'revids=23512' ''', where revid is the next revision id in order.
api.php ? action=query & what=revisions & revids=12345 & rvprop=timestamp & rvlimit=10 & rvdir=older
: Get the timestamps of all revisions between two given revision IDs. rvlimit is optional. If the number of revisions exceeds the limit, the 'revisions' element will contain ''' 'continue':'rvstartid=23512' ''' with the revid to continue from. Both rvstartid & rvendid must belong to the same title. The titles= parameter is not required, but if given, it must be set to the same title as revision IDs.
api.php ? action=query & what=revisions & rvprop=timestamp & rvstartid=12345 & rvendid=67890

==== Lists ====
Lists differ from other properties in one important aspect - their output is limited by number of items, and may be continued using "paging" technique. Even when no limit is provided, the query will only return a set number of items, and will also provide a string from which to continue paging. See All Pages list for an example.

===== allpages (ap) =====
: Returns a list of pages in a given namespace starting at ''from'', ordered by page title.
: Parameters: from (paging), namespace (dflt=0), redirect (flt), limit (dflt=10, max=500/5000)

: Example: Request a list of 3 pages from namespace 10 (templates) begining at the letter A.
'''Request:'''
api.php ? action=query & list=allpages & apnamespace=10 & aplimit=3 & apfrom=A
'''Result:'''
api:
query:
allpages:
Template:A-Article:
id: 12341
ns: 10
Template:B-Article:
id: 12342
ns: 10
Template:C-Article:
id: 12343
ns: 10
query-status:
allpages:
continue: apfrom=D-Article ''The next item in this list would have been Template:D-Article.''
: The client may now make another request using the ''continue'' value as a parameter:
api.php ? action=query & list=allpages & apnamespace=10 & aplimit=3 & apfrom=D-Article

===== backlinks (bl) =====
: Lists pages that link to the given page. Ordered by linking page title.
: Parameters: title, from (paging), namespace (flt), redirect (flt), limit (dflt=10, max=500/5000)
api.php ? action=query & list=backlinks & blnamespace=10 & blfrom=A & bltitle=ArticleA

===== categorymembers (cm) =====
: List of pages that belong to a given category, ordered by page title.
: Parameters: title, from (paging), namespace (flt), limit (dflt=10, max=500/5000)

===== embeddedin (ei) =====
: What pages include ''title'' page as a template. List of pages that include the given page using <nowiki>{{title}}</nowiki>. Ordered by including page title.
: Parameters: title, from (paging), namespace (flt), redirect (flt), limit (dflt=10, max=500/5000)
api.php ? action=query & list=embeddedin & einamespace=10

===== imagelinks (il) =====
: List of pages that include a given image. Ordered by page title.
: Parameters: image title, from (paging), namespace (flt), limit (dflt=10, max=500/5000)

===== logevents (le) =====
: List log events, filtered by time range, event type, user type, or the page it applies to. Ordered by event timestamp.
: Parameters: type (flt), from (paging timestamp), to (flt), direction (dflt=older), limit (dflt=10, max=500/5000), user (flt), title (flt)

===== recentchanges (rc) =====
: Gets a list of pages recently changed, ordered by modification timestamp.
: Parameters: from (paging timestamp), to (flt), namespace (flt), minor (flt), usertype (dflt=!bot), direction (dflt=older), limit (dflt=10, max=500/5000)

===== usercontribs (uc) =====
: Gets a list of pages modified by a given user, ordered by modification time.
: Parameters: user, from (paging timestamp), to (flt), namespace (flt), minor (flt), top (flt), direction (dflt=older), limit (dflt=10, max=500/5000)

===== users (us) =====
: Gets a list of registered users, ordered by user name.
: Parameters: from (paging), limit (dflt=10, max=500/5000)

===== watchlist (wl) =====
: Get a list of pages on the user's watchlist but only if they were changed within the given time period. Ordered by time of the last change of the watched page.
: Parameters: from (paging timestamp), to (flt), namespace (flt), direction (dflt=older), limit (dflt=10, max=500/5000)

==== Generators ====
Generator is way to use one of the [[#lists]] instead of the titles= parameter. The output of the list must be a list of pages, whose titles get automatically appended to the titles= parameter separated by the pipe '|' symbol. Other queries such as content, revisions, etc, will treat those pages as if they were provided by the user in the titles= parameter. Only one generator is allowed, and while it is possible to have both generator= and list= parameters in the same call, they may not contain the same values.

: Example: Use the allpages list as a generator, to get the links and categories for all titles returned by allpages.
'''Request:'''
api.php ? action=query & generator=allpages & apnamespace=3 & aplimit=10 & apfrom=A & what=links|categories
'''Result:'''
api:
query:
pages:
Template:A-Article:
id: 12341
ns: 10
links:
Linked Article1: ''Linked Article1 is in the main namespace''
Talk:Linked Article2: ''For non-main ns, list it as a subelement''
ns: 1
...
categories:
Category:Cat1:
Category:Cat2:
...
Template:B-Article:
...
Template:C-Article:
...
query-status:
allpages:
continue: apfrom=D-Article ''The next item in this list would have been Template:D-Article.''

=== Save ===
'''Request:'''
api.php ? action=save & title=Project:articleA & edittoken=abc123 & summary=...lalala... & content=...wikitext...
'''Result:'''
api:
save:
status: Success ''Other values: 'Prohibited', 'Conflict', 'DbLcoked', 'BadToken''''
title: Wikipedia:ArticleA ''Always returns normalized title''
ns: 4 ''Show title's namespace except when ns=0''
revid: 67891 ''On success, the new latest revision id''

== Wikimania 2006 API discussion ==
''See [[/Wikimania 2006 API discussion]].''

Latest revision as of 06:02, 22 February 2022

Moved preserving full histories. robchurch | talk 07:09, 14 May 2007 (UTC)[reply]

Retrieved from "https://meta.wikimedia.org/w/index.php?title=API&oldid=22874713"