Extension:Wikibase Repository/API2


 * See also Extension:Wikibase/API and Extension:Wikibase/API1

Additional API specification for Wikibase are additional description of how the API modules for Wikibase are supposed to work. This is not a complete description, check the [//en.wikipedia.org/w/api.php API's documentation] (localhost) for further details.

Prop modules
There are some general parameters that are very useful. Those are format, smaxage, maxage, maxlag and requestid. Parameter format is used to define the return format, usually always set to json. Parameter smaxage and maxage is used to interact with caching. Parameter maxlag is used for throttling of requests, use longer times for more important requests. Parameter requestid it can be used where several requests are handled in parallel.


 * Example normalized result : This is really a lookup with some transformation and then the result of the final landing page. Note that several normalizations can be done for a single page.


 * Example redirected result : This is really a lookup through a label/alias and then the result of the final landing page. This page could be a redirect, unless the API is told to follow through to the final page. Note that several normalizations (also redirects) can be done for a single page.


 * Example failed result : This could imply some attempt to normalize in addition (and most often will).


 * Links for testing
 * |site|language&wbatest&format=jsonfm List wbaliases as JSONfm with testdata
 * |site|language&wbatest&format=xmlfm List wbaliases as XMLfm with testdata
 * |wbdescriptions&wbdtest&wbltest&format=jsonfm List both wblabels and wbdescriptions as JSONfm with testdata
 * |wbdescriptions&wbdtest&wbltest&format=xmlfm List both wblabels and wbdescriptions as XMLfm with testdata

wbaliases
See also api-generated [//en.wikipedia.org/w/api.php?action=help&modules=query module help] and paraminfo (localhost until labs up and running module help and paraminfo).

This module should be accessed with the GET verb.

Needs some work as it doesn't get back real data, but works with testdata for [//en.wikipedia.org/w/api.php?action=query&list=wbaliases&wbatest&format=jsonfm jsonfm] and [//en.wikipedia.org/w/api.php?action=query&list=wbaliases&wbatest&format=xmlfm xmlfm] (localhost until labs up and running jsonfm and xmlfm).


 * Parameters
 * ids – Integer – handled by the query module
 * titles – String – handled by the query module
 * list – Values (separate with '|'): aliases, labels, descriptions.
 * format – Integer – handled by the query module
 * wbaprop – Values (separate with '|'): language, alias, site.
 * redirects – Automatically resolve redirects. Default is false. (not implemented)


 * Example normal result : This is a slight rewamp of the result on Wikidata/Data_model/JSON to accommodate for normal output as given by prop=info.

''This module could be reimplemented as a query module. If its not a query module then it should only return data for one single item (with exact match) and fail if this is not found. Note that even if zero or one item (entity described on a single page) will be returned the structure still use the same name.''

wblabels
See also api-generated [//en.wikipedia.org/w/api.php?action=help&modules=query module help] and paraminfo (localhost until labs up and running module help and paraminfo).

This module should be accessed with the GET verb.

Needs some work as it doesn't get back real data, but works with testdata for [//en.wikipedia.org/w/api.php?action=query&list=wblabels&wbdtest&format=jsonfm jsonfm] and [//en.wikipedia.org/w/api.php?action=query&list=wblabels&wbdtest&format=xmlfm xmlfm] (localhost until labs up and running jsonfm and xmlfm).


 * Parameters
 * ids – Integer – handled by the query module
 * titles – String – handled by the query module
 * list – Values (separate with '|'): aliases, labels, descriptions.
 * format – Integer – handled by the query module
 * wblprop – Values (separate with '|'): language, label.
 * redirects – Automatically resolve redirects. Default is false. (not implemented)


 * Example normal result : This is a slight rewamp of the result on Wikidata/Data_model/JSON to accommodate for normal output as given by prop=info.

''This module could be reimplemented as a query module. If its not a query module then it should only return data for one single item (with exact match) and fail if this is not found. Note that even if zero or one item (entity described on a single page) will be returned the structure still use the same name.''

wbdescriptions
See also api-generated [//en.wikipedia.org/w/api.php?action=help&modules=query module help] and paraminfo (localhost until labs up and running module help and paraminfo).

This module should be accessed with the GET verb.

Needs some work as it doesn't get back real data, but works with testdata for [//en.wikipedia.org/w/api.php?action=query&list=wbdescriptions&wbdtest&format=jsonfm jsonfm] and [//en.wikipedia.org/w/api.php?action=query&list=wbdescriptions&wbdtest&format=xmlfm xmlfm] (localhost until labs up and running jsonfm and xmlfm).


 * ids – Integer – handled by the query module
 * titles – String – handled by the query module
 * list – Values (separate with '|'): aliases, labels, descriptions.
 * format – Integer – handled by the query module
 * wbdprop – Values (separate with '|'): language, label.
 * redirects – Automatically resolve redirects. Default is false. (not implemented)


 * Example normal result : This is a slight rewamp of the result on Wikidata/Data_model/JSON to accommodate for normal output as given by prop=info.

''This module could be reimplemented as a query module. If its not a query module then it should only return data for one single item (with exact match) and fail if this is not found. Note that even if zero or one item (entity described on a single page) will be returned the structure still use the same name.''

Top-level modules
Note that for editing operations the client (usually the browser) must first request an edit token.


 * Example normalized result : This is really a lookup with some transformation and then the result of the final landing page. Note that several normalizations can be done for a single page.


 * Example redirected result : This is really a lookup through a label/alias and then the result of the final landing page. This page could be a redirect, unless the API is told to follow through to the final page. Note that several normalizations (also redirects) can be done for a single page.


 * Example failed result : This could imply some attempt to normalize in addition (and most often will).

wbitem
See also [//en.wikipedia.org/w/api.php?action=help&modules=wbgetitem api-generated help] (localhost).

This module should be accessed with the GET verb. When an item is accessed through this module some assumptions are done compared to the props module.


 * Parameters
 * id – Integer
 * title – String
 * language – check the api
 * prop – Values (separate with '|'): info, pageid, ns, title, touched, lastrevid, counter, length, aliases, labels, descriptions. Default is all. Note that info will be pageid, ns, title, touched, lastrevid, counter and length.
 * redirects – Automatically resolve redirects. Default is false.


 * Example normal result : This is a slight rewamp of the result on Wikidata/Data_model/JSON to accommodate for normal output as given by prop=info.

''This module could be reimplemented as a query module. If its not a query module then it should only return data for one single item (with exact match) and fail if this is not found. Note that even if zero or one item (entity described on a single page) will be returned the structure still use the same name.''

wbassociate
See also [//en.wikipedia.org/w/api.php?action=help&modules=wbassociate api-generated help] (localhost).


 * Parameters
 * id
 * wiki
 * title
 * badge – String, overrides existing badges if given.

''This is an edit operation and as such needs a valid edit token supplied by a user allowed to edit. It must also be a POST request.''

wblink
See also [//en.wikipedia.org/w/api.php?action=help&modules=wblink api-generated help] (localhost).

For this to work an assumption must be made that Wikibase acquire necessary tokens on the external sites and checks if the user has edit rights on the sites and for the specific pages. If not he module will do a preemptive fail on the edit. If the edit on any of the sites (including the internal one) later fails the edits on the other ones must be rolled back.


 * Parameters
 * id – Integer, internal page id for linkage
 * language-from
 * title-from
 * badge-from – String, overrides existing badges if given.
 * language-to
 * title-to
 * badge-to – String, overrides existing badges if given.
 * wiki – String
 * redirects – Automatically resolve redirects. Default is false.
 * token – String


 * Example normal result : This is a slight rewamp of the result on m:API:Edit.

''This is an edit operation and as such needs a valid edit token supplied by a user allowed to edit. It must also be a POST request.''

wbalias
''See also [//en.wikipedia.org/w/api.php?action=help&modules=wbalias api-generated help] (localhost) and the section EntityDescriptions of Items and Properties at the background page Data model. The alias refers to the page on the external wiki.''

According to a REST philosophy this module should be accessed with a PUT verb to set the value, but lacking a delete argument a POST verb will act like a PUT. A symmetric GET verb will then return the set value. Giving a delete without having delete rights will be an error. Doing a PUT without a preexisting value will create it, if the value do exist oldrevid and newrevid will be equal. Using the GET verb together with the delete argument will lead to an exception. A successful delete of an old value will lead to a new revision.


 * Parameters
 * id – Integer
 * title – String
 * language – check the api
 * wiki – String
 * alias – String
 * redirects – Automatically resolve redirects. Default is false.
 * token – String
 * delete – Default false.


 * Example normal result : This is a slight rewamp of the result on m:API:Edit.

''This is an edit operation and as such needs a valid edit token supplied by a user allowed to edit. It could also be accessed a POST request.''

wbdescription
See also [//en.wikipedia.org/w/api.php?action=help&modules=wbdescription api-generated help] (localhost) and the section EntityDescriptions of Items and Properties at the background page Data model.

According to a REST philosophy this module should be accessed with a PUT verb to set the value, but lacking a delete argument a POST verb will act like a PUT. A symmetric GET verb will then return the set value. Giving a delete without having delete rights will be an error. Doing a PUT without a preexisting value will create it, if the value do exist oldrevid and newrevid will be equal. Using the GET verb together with the delete argument will lead to an exception. A successful delete of an old value will lead to a new revision.


 * Parameters
 * id – Integer
 * title – String
 * language – check the api
 * description – String
 * redirects – Automatically resolve redirects. Default is false.
 * token – String


 * Example normal result : This is a slight rewamp of the result on m:API:Edit.

This is an edit operation and as such needs a valid edit token supplied by a user allowed to edit.

wblabel
See also [//en.wikipedia.org/w/api.php?action=help&modules=wblabel api-generated help] (localhost) and the section EntityDescriptions of Items and Properties at the background page Data model.

According to a REST philosophy this module should be accessed with a PUT verb to set the value, but lacking a delete argument a POST verb will act like a PUT. A symmetric GET verb will then return the set value. Giving a delete without having delete rights will be an error. Doing a PUT without a preexisting value will create it, if the value do exist oldrevid and newrevid will be equal. Using the GET verb together with the delete argument will lead to an exception. A successful delete of an old value will lead to a new revision.


 * Parameters
 * id – Integer
 * title – String
 * language – check the api
 * label – String
 * redirects – Automatically resolve redirects. Default is false.
 * token – String


 * Example normal result : This is a slight rewamp of the result on m:API:Edit.

This is an edit operation and as such needs a valid edit token supplied by a user allowed to edit.

SearchByName
Not implemented during Phase I as this would need some kind of searchable store, most likely a NoSQL store of some kind.

Exceptions
Exceptions may or may not be returned as web pages, but will be structured according for format if the exception is a prepared and expected condition.

See also API:Errors and warnings

Warnings

 * Use a valid warning situation as example.

A warning condition may be given together with the normal output, and it will indicate a situation where the output can be erroneous.

If the warning condition is prepared and expected, and a format is defined, it will have the following form when  is set (example)

Note that  is the default format and will give the help page.

Errors
If the error condition is prepared and expected, and a format is defined, it will have the following form when the  is set (example)

Note that  is the default format and will give the help page.

Not implemented
Typical error message when an function is not implemented and  is set (example – only works with the extension)

or when the  is set (example – only works with the extension)

Todo

 * Link to the correct instance at the labs cloud.