Jump to content

Extension:Wikibase Repository/API1

From mediawiki.org
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 API's documentation (localhost) for further details.

Actions

[edit]

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

[edit]

See also 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 Wikibase/DataModel/JSON to accommodate for normal output as given by prop=info.
{
	"wbgetitem": {
		"page": {
			"pageid": 15580374,
			"ns": 0,
			"title": "q7",
			"touched": "2012-04-12T00:47:07Z",
			"lastrevid": 485846286,
			"counter": "",
			"length": 6393,
			"wikis": { // 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"
				}
			}
		}
	}
}
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.
{
	"wbgetitem": {
		"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.
{
	"wbgetitem": {
		"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).
{
	"wbgetitem": {
		"page": {
			"ns": 0,
			"id": 123456,
			"missing": ""
		}
	}
}

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

[edit]

See also api-generated help (localhost).

This is an optimization for GetItem where prop=pageid 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

[edit]

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 Wikibase/DataModel/JSON to accommodate for normal output as given by prop=info.
{
	"wbgetitem": {
		"pages": {
			"15580374": {
				"pageid": 15580374,
				"ns": 0,
				"title": "q7",
				"touched": "2012-04-12T00:47:07Z",
				"lastrevid": 485846286,
				"counter": "",
				"length": 6393,
				"wikis": { // 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"
					}
				}

			}
		}
	}
}
Example normalized result
This is really a lookup with some transformation and then the result of the final landing page.
{
	"wbgetitem": {
		"normalized": [
			{
				"from": "foo_bar",
				"to": "Foo bar"
			}
		],
		"pages": {
			// deleted stuff
		}
	}
}
Example redirected result
This is really a lookup through a label/alias and then the result of the final landing page. (?)
{
	"wbgetitem": {
		"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).
{
	"wbgetitem": {
		"pages": {
			"-1": {
				"ns": 0,
				"title": "q123456",
				"missing": ""
			}
		}
	}
}

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

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

LinkArticles

[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.
{
	"wblinkarticles": {
		"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.

AddAlias

[edit]

See also api-generated help (localhost) and the section EntityDescriptions of Items and Properties at the background page Wikibase/DataModel. 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#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 must also be a POST request.

RemoveAlias

[edit]

See also 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#Example.
{
	"wbremovealias": {
		"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 must also be a POST request.

SetDescription

[edit]

See also api-generated help (localhost) and the section EntityDescriptions of Items and Properties at the background page Wikibase/DataModel.

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#Example.
{
	"wbsetdescription": {
		"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.

RemoveDescrition

[edit]

See also 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#Example.
{
	"wbremovedescription": {
		"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.

SetLabel

[edit]

See also api-generated help (localhost) and the section EntityDescriptions of Items and Properties at the background page Wikibase/DataModel.

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#Example.
{
	"wbsetlabel": {
		"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.

RemoveLabel

[edit]

See also 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#Example.
{
	"wbremovelabel": {
		"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.

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 Wikibase/DataModel/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 Wikibase/DataModel/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 Wikibase/DataModel/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.

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=xml is set (example)

<api servedby="mw32">
	<warning code="unknown_action" info="Unrecognized value for parameter 'action': blah"/>
</api>

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

<api servedby="mw32">
	<error code="unknown_action" info="Unrecognized value for parameter 'action': blah"/>
</api>

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