Extension:Wikibase Repository/API2

From MediaWiki.org
Jump to navigation Jump to search
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 API's documentation (localhost) for further details.

Prop modules[edit]

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.

{ "wbitems": { "normalized": [ { "from": "foo_bar", "to": "Foo bar" } ], "pages": { "15580374": { // deleted stuff } } } }

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.

{ "wbitems": { "normalized": [ { "from": "Foobar", "to": "Barfoo" } ], "pages": { "15580374": { // deleted stuff "redirect": "" } } } }

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

{ "wbitems": { "pages": { "15580374": { "ns": 0, "id": 123456, "missing": "" } } } }

Links for testing

wbaliases[edit]

See also api-generated 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 jsonfm and 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 m:Wikidata/Data_model/JSON to accommodate for normal output as given by prop=info.

{ "wbitems": { "pages": { "15580374": { "pageid": 15580374, "ns": 0, "title": "q7", "aliases": [ { "language" : "en", "site" : "wikipedia", "alias" : "Georgia_(country)" }, { "language" : "de", "site" : "wikipedia", "alias" : "Georgien" } ] } } } }

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[edit]

See also api-generated 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 jsonfm and 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 m:Wikidata/Data_model/JSON to accommodate for normal output as given by prop=info.

{ "wbitems": { "pages": { "15580374": { "pageid": 15580374, "ns": 0, "title": "q7", "labels": [ { "language" : "en", "label" : "Georgia" }, { "language" : "de", "label" : "Georgien" } ] } } } }


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[edit]

See also api-generated 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 jsonfm and 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 m:Wikidata/Data_model/JSON to accommodate for normal output as given by prop=info.

{ "wbitems": { "pages": { "15580374": { "pageid": 15580374, "ns": 0, "title": "q7", "descriptions": [ "en" : { "language" : "en", "description" : "A central-asian country" }, "de" : { "language" : "de", "description" : "Land im Kaukasus" } ] } } } }

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[edit]

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.

{ "wbitems": { "normalized": [ { "from": "foo_bar", "to": "Foo bar" } ], "page": { // deleted stuff } } }

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.

{ "wbitems": { "normalized": [ { "from": "Foobar", "to": "Barfoo" } ], "page": { // deleted stuff "redirect": "" } } }

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

{ "wbitems": { "page": { "ns": 0, "id": 123456, "missing": "" } } }

wbitem[edit]

See also 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 m:Wikidata/Data_model/JSON to accommodate for normal output as given by prop=info.

{ "wbitems": { "page": { "pageid": 15580374, "ns": 0, "title": "q7", "touched": "2012-04-12T00:47:07Z", "lastrevid": 485846286, "counter": "", "length": 6393, "aliases": { // external pages "en" : { "language" : "en", "value" : "Georgia_(country)" }, "de" : { "language" : "de", "value" : "Georgien" } }, "labels" : { // internal aliases "en" : { "language" : "en", "value" : "Georgia" }, "de" : { "language" : "de", "value" : "Georgien" } }, "descriptions" : { "en" : { "language" : "en", "value" : "A central-asian country" }, "de" : { "language" : "de", "value" : "Land im Kaukasus" } } } } }

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[edit]

See also 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[edit]

See also 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#Example.

{ "wblink": { "page": { // this is the internal page "result": "Success", "pageid": 12, "title": "q1234567", "oldrevid": 465, "newrevid": 471 }, "from": { // this is the external from-page "result": "Success", "pageid": 12, "title": "Norway", "oldrevid": 465, "newrevid": 471 }, "to": { // this is the external from-page "result": "Success", "pageid": 12, "title": "Norge", "oldrevid": 465, "newrevid": 471 } } }

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[edit]

See also api-generated help (localhost) and the section EntityDescriptions of Items and Properties at the background page m: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#Example.

{ "wbaddalias": { "result": "Success", "pageid": 12, "title": "q1234567", "oldrevid": 465, "newrevid": 471 } }

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[edit]

See also api-generated help (localhost) and the section EntityDescriptions of Items and Properties at the background page m: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#Example.

{ "wbdescription": { "result": "Success", "pageid": 12, "title": "q1234567", "oldrevid": 465, "newrevid": 471 } }

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

wblabel[edit]

See also api-generated help (localhost) and the section EntityDescriptions of Items and Properties at the background page m: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#Example.

{ "wblabel": { "result": "Success", "pageid": 12, "title": "q1234567", "oldrevid": 465, "newrevid": 471 } }

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

SearchByName[edit]

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

Exceptions[edit]

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[edit]

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 format=jsonfm is set (example) { "servedby": "srv273", "warning": { "code": "unknown_action", "info": "Unrecognized value for parameter 'action': blah" } }

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

Errors[edit]

If the error condition is prepared and expected, and a format is defined, it will have the following form when the format=jsonfm is set (example) { "servedby": "srv273", "error": { "code": "unknown_action", "info": "Unrecognized value for parameter 'action': blah" } }

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

Not implemented[edit]

Typical error message when an function is not implemented and format=xmlfm is set (example – only works with the extension) <api> <error code="internal_api_error_MWException" info="Exception Caught: Internal error in ApiWikibaseGetItem::execute: Unhandled case value: " xml:space="preserve"> <!-- hidden stacktrace --> </error> </api>

or when the format=jsonfm is set (example – only works with the extension) { "error": { "code": "internal_api_error_MWException", "info": "Exception Caught: Internal error in ApiWikibaseGetItem::execute: Unhandled case value: ", "*": "\n" /* hidden stacktrace */ } }

See also[edit]

Todo[edit]

  • Link to the correct instance at the labs cloud.