Extension:Wikibase Repository/API1


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

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.

Actions
Note that for editing operations the client (usually the browser) must first request an edit token.

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.

GetItem
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.


 * Parameters
 * id – Integer
 * title – String
 * language – check the api
 * prop – Values (separate with '|'): info, pageid, titles, labels, descriptions. Default is all. Note that info will include pageid.
 * 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.


 * 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).

''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.''

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

This is an optimization for GetItem where  and only title will be accepted in the request.

This module should be accessed with the GET verb.

''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.''

QueryItem
Probably not implemented during Phase I. Note that this only needs the ability to iterate over ordinary page titles and page ids.


 * Parameters : To be defined.


 * 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.


 * Example normalized result : This is really a lookup with some transformation and then the result of the final landing page.


 * Example redirected result : This is really a lookup through a label/alias and then the result of the final landing page. (?)


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

''This module should be able to return data for multiple items (with exact match on each of them) and fail if none are found. Note that even if only one item (entity described on a single page) will be returned the structure still use a plural form (entities described on several found pages).''

AssociateArticle
See also [//en.wikipedia.org/w/api.php?action=help&modules=wbassociatearticle 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.''

LinkArticles
See also [//en.wikipedia.org/w/api.php?action=help&modules=wblinkarticles 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.''

AddAlias
''See also [//en.wikipedia.org/w/api.php?action=help&modules=wbaddalias 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.''

This module should be accessed with the POST verb. According to a REST philosophy it can be argued that this should be a PUT verb. If accessed by a PUT verb the action could be named wbalias. A symmetric GET verb will then return the set value.


 * Parameters
 * id – Integer
 * title – String
 * language – check the api
 * wiki – String
 * alias – 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.''

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

This module should be accessed with the POST verb. If accessed by a POST verb the action could be named wbalias and then use an additional remove argument.


 * Parameters
 * id – Integer
 * title – String
 * language – check the api
 * wiki – String
 * redirects – Automatically resolve redirects. Default is false.
 * remove – Delete the identified page. 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.''

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

This module should be accessed with the POST verb. According to a REST philosophy it can be argued that this should be a PUT verb. If accessed by a PUT verb the action could be named wbdescription. A symmetric GET verb will then return the set value.


 * 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.

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

This module should be accessed with the POST verb. If accessed by a POST verb the action could be named wbdescription and then use an additional remove argument.


 * Parameters
 * id – Integer
 * title – String
 * language – check the api
 * redirects – Automatically resolve redirects. Default is false.
 * remove – Delete the identified page. 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.

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

This module should be accessed with the POST verb. According to a REST philosophy it can be argued that this should be a PUT verb. If accessed by a PUT verb the action could be named wblabel. A symmetric GET verb will then return the set value.


 * 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.

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

This module should be accessed with the POST verb. If accessed by a POST verb the action could be named wblabel and then use an additional remove argument.


 * Parameters
 * id – Integer
 * title – String
 * language – check the api
 * redirects – Automatically resolve redirects. Default is false.
 * remove – Delete the identified page. 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.

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.''

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)

or when the  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  is set (example)

or 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.