Wikibase/API

Historical versions API1, API2, API3, API4.

Work in progress!!

Wikibase API for the repo part, that is the part running on the central database with its database. There is a separate API for the clients, or in Wikidata lingo the attached wiki sites. There can be browsers connected to both the repo and the clients.

Requests to the repo API that changes content should use token, be aware of rights, use POST or GET requests according to mode (use POST to avoid problem with non-behaving proxies), and be aware of and handle errors from the API.

Modules
There are some parameters that is always available, and some that are nearly always available. Plural forms are used in those cases where a parameter can take several values.


 * id | ids : Identifies a specific item or items. Plural form is used in wbgetitems.
 * site ∩ title | sites ∩ titles : Identifies a single item or multiple items. Plural form is used in wbgetitems. Only one of sites and titles can have multiple values at the same time.
 * language | languages : The language is used as a filter mechanism to filter labels and descriptions in get actions or to identify a specific language for set actions.
 * format : Should always be set to json (or jsonfm for debugging), or xml (or xmlfm for debugging), no other form is supported.
 * usekeys | nousekeys : Add keys (or do not add them) to some structures, if some formats are used, and will be silently ignored for other formats. Specifically it will be used for the json, yaml and raw formats. One of usekeys and nousekeys will be enabled according to whats defined in the default config and possibly LocalSettings.php.

Normally the return value either has a success key with a boolean cast as an integer or an error key with an object of two, optionally three, keys code, info and "*". The last one is additional information. Information about the action is either passed on the top level or under item if its one single item or items if its several. If it is several items each is found under a key with its own item id.


 * Note that empty objects are returned as json arrays and not as objects.
 * Note that the parameters item and link is not supported anymore.
 * Note that empty parameters removes the actual entry from the item.
 * Note that attribute in wbsetlanguageattribute is not supported anymore.

wbgetitemid [deprecated]
Note this module is not supported anymore, use wbgetitems with an empty props.

wblinksite [deprecated]
Note this module is now called wbsetsitelink, and the link parameter is not supported anymore.

wbsetsitelink
Module to define new links to pages at external client sites. During processing of requests the module will query the external site to verify the existence of the page and to acquire the canonical form of the prefix and the pagename. linkSite( ( id XOR ( site, title ) ), linksite, linktitle, *summary)
 * id is the numeric identifier for an existing item, if the item does not exist an error is returned.
 * site ∩ title is a pair that identifies a single existing item, if the item does not exist an error is returned.
 * linksite is the site id for a client site that will be the target of the new link. The site will be queried during the call.
 * linktitle is the title of the page at the client site that will be the target of the new link. The site will be queried during the call.
 * summary is a user entered string that is used in addition to an autocomment generated by the module itself.

{ 	"item": { "sitelinks": { "nowiki": { "site": "nowiki", "title": "Mickepedia" } 		}, 		"id": 42 }, 	"success": 1 }
 * Example with use of site-title pair : http://localhost/repo/api.php?action=wbsetsitelink&site=nowiki&title=Foo&linksite=nowiki&linktitle=Mickepedia&format=jsonfm

{ 	"item": { "sitelinks": { "nowiki": { "site": "nowiki", "title": "Foo" } 		}, 		"id": 42 }, 	"success": 1 }
 * Example with use of id : http://localhost/repo/api.php?action=wbsetsitelink&id=42&linksite=nowiki&linktitle=Foo&format=jsonfm

wbsetlanguageattribute
Module to set label and description for a specific language. The language must be an existing and maintained language, and the label and description will be normalized. setLanguageAttribute(id XOR (site, title), (language AND (label OR description)), *summary)
 * id is the numeric identifier for an existing item, if the item does not exist an error is returned.
 * site ∩ title is a pair that identifies a single existing item, if the item does not exist an error is returned.
 * label is the new value for the label in the given language. The string wil be normalized.
 * description is the new value for the description in the given language. The string wil be normalized.
 * language is the language for the label and description. The language must be a valid identifier.
 * summary is a user entered string that is used in addition to an autocomment generated by the module itself.

{ 	"item": { "labels": { "en": { "language": "en", "value": "Cyberdyne" } 		}, 		"id": 42 }, 	"success": 1, }
 * Example changing label : http://localhost/repo/api.php?action=wbsetlanguageattribute&id=42&language=en&label=Cyberdyne&format=jsonfm

{ 	"item": { "descriptions": { "sv": { "language": "sv", "value": "Place where Alice lived for a short time" } 		}, 		"id": 2 }, 	"success": 1 }
 * Example changing description : http://localhost/repo/api.php?action=wbsetlanguageattribute&id=2&language=sv&description=Place%20where%20Alice%20lived%20for%20a%20short%20time&format=jsonfm

{ 	"item": { "labels": { "en": { "language": "en", "removed": "" } 		}, 		"id": 42 }, 	"success": 1, }
 * Example removing label : http://localhost/repo/api.php?action=wbsetlanguageattribute&id=42&language=en&label=&format=jsonfm

wbdeletelanguageattribute [deprecated]
Note this module is not supported anymore, use wbsetlanguageattribute with empty label or description.

wbgetsitelinks [deprecated]
Note this module is not supported anymore, use wbgetitems with props set to sitelinks.

wbgetitems
Module to get the content of several items, possibly with only parts of the item included. Items that are checked for existens, but not found, are reported. During lookup only one of sites and titles can be a list. getItems( ( ids XOR ( sites, titles )) ), *props, *languages)
 * ids are numeric identifiers for existing items, if the items does not exist they will be marked as missing.
 * sites ∩ titles is pairs that identifies multiple existing items, if the items does not exist they will be marked as missing.
 * props which list to report, possibly filtered by language if they are language specific. Note that sitelinks are not language specific.
 * languages are one or more languages to filter the list against. If it is missing all valid languages are reported.
 * summary is a user entered string that is used in addition to an autocomment generated by the module itself.

{ 	"items": { "42": { 			"id": 42, "sitelinks": { "enwiki": { "site": "enwiki", "title": "Death Star" }, 			}, 			"descriptions": { "en": { "language": "en", "value": "Nice place for old men with rhesphiratorry prroblemsss" } 			}, 			"labels": { "en": { "language": "en", "value": "Death Star" }, 				"nn": { "language": "nn", "value": "Dødsstjerna" } 			} 		} 	}, 	"success": 1 }
 * Example of general lookup with id : http://localhost/repo/api.php?action=wbgetitems&ids=42&format=jsonfm

{ 	"items": { "42": { 			"id": 42, "labels": { "nn": { "language": "nn", "value": "Dødsstjerna" } 			} 		} 	}, 	"success": 1 }
 * Example of limited lookup with site-title pair: http://localhost/repo/api.php?action=wbgetitems&sites=enwiki&titles=Death_Star&props=labels&languages=nn&format=jsonfm

wbsetitem
''Note that this module is an interim solution to create and test items, and can change without further notice. The module itself can be removed in the final system. The solution is unsupported and any behavior is a feature or bug at the developers discretion.'' getItems( data )
 * Example : http://localhost/repo/api.php?action=wbsetitem&data={}&format=jsonfm
 * Builds an empty item, then returns a representation of the created structure. Note that a created structure will have an id for the item, but even if it gets an id it may not be a valid item.

{ 	"item": { "id": 9 }, 	"success": 1 }


 * Example : http://localhost/repo/api.php?action=wbsetitem&data={%22label%22:{%22de%22:%22de-value%22,%22en%22:%22en-value%22}}&format=jsonfm
 * Builds an item with a few labels set, then returns the structure. Note that the structure is not similar and that there is a naming difference in label used in the input and labels used in the output.

{ 	"item": { "id": 11, "labels": { "de": { "language": "de", "value": "de-value" }, 			"en": { "language": "en", "value": "en-value" } 		} 	}, 	"success": 1 }

wbsetaliases
Module to set, add and remove aliases from items. Aliases are alternate names for the items, that can be queried and used for lookup. setAliases(id XOR (site, title), (add OR remove) XOR set, *summary)
 * id is the numeric identifier for an existing item, if the item does not exist an error is returned.
 * site ∩ title is a pair that identifies a single existing item, if the item does not exist an error is returned.
 * set contains a list of strings that will be used as the new list of aliases. The values are normalized before they are used.
 * add contains a list of additional strings that will be used as aliases. The values are normalized before they are used.
 * remove contains a list of strings that will be removed from the the list of aliases. The values are normalized before they are used.
 * summary is a user entered string that is used in addition to an autocomment generated by the module itself.

{ 	"success": 1, "item": { "aliases": { "en": [ { 					"language": "en", "value": "Foo" }, 				{ 					"language": "en", "value": "Bar" } 			] 		}, 		"id": 42 } }
 * Example set Foo and Bar : http://localhost/repo/api.php?action=wbsetaliases&language=en&id=5&set=Foo|Bar&format=jsonfm

{ 	"success": 1, "item": { "aliases": { "en": [ { 					"language": "en", "value": "Foo" }, 				{ 					"language": "en", "value": "Bar" }, 				{ 					"language": "en", "value": "Test" } 			] 		}, 		"id": 42 } }
 * Example add Test : http://localhost/repo/api.php?action=wbsetaliases&language=en&id=5&add=Test&format=jsonfm

{ 	"success": 1, "item": { "aliases": { "en": [ { 					"language": "en", "value": "Bar" } 			] 		}, 		"id": 42 } }
 * Example remove Foo and Test : http://localhost/repo/api.php?action=wbsetaliases&language=en&id=5&remove=Foo|Test&format=jsonfm

wbsearchbyname (partly)
This call is only partly implemented as it is not clear how the search should be done. searchByName(language, fragment, *hints)

Token
All call to content changing API functions should be developed for (and prepared to) use the token. That includes Wikidata items and other associated pages. For the moment only one token is in use. Such tokens must be acquired before any operations that needs them are accessed or the operation will fail.

If the API is in debug mode, that is by setting apiInDebug to true, the use of tokens will be disabled. It is reenabled by setting apiDebugWithTokens to true. A production environment ''should' not disable use of tokens.

Tokens are in ver. 0.1 acquired by a request to wbsetitem with gettoken in the URL
 * example : http://localhost/repo/api.php?action=wbsetitem&gettoken&format=jsonfm

After the reply comes back the token named setitemtoken is the one that is used for all later requests. { 	"wbsetitem": { "setitemtoken": "a462a54d500848fa53a808fc26478dd4+\\" } }

The current implementation is implemented as a API only solution, and the mw.user.tokens list is not populated with additional elements. See also subsection tokens in default modules.

Note that as default the API will require POST requests.

The API should use salted tokens for each item.

See also Manual:Edit token.

Rights
All call to content changing API functions should be developed for (and prepared to) use rights. That includes errors due to insufficient access rights. That imply that it could be necessary to be logged in before content can be changed. The basic access rights write rights is in addition to the permissions.

If the API is in debug mode, that is by setting apiInDebug to true, the use of rights will be disabled. It is reenabled by setting apiDebugWithRights to true. A production environment should not disable use of rights.

Rights are named as "module-operation" and added to a group wbeditor. This could be reorganized into other groups or be divided as more fine grained rights or reorganized in other ways. The module name is shortened to make them more manageable.

In the current setup there are no read rights and there are also no default write rights for anonymous users. It seems likely that a setup for Wikipedia will assign add, update and set rights to anonymous users.

Note that with the default setup it is necessary to log in to the site, either through the usual web interface for the site or through global login (SUL).

Setup
$wgGroupPermissions['wbeditor']['item-add']         = true; $wgGroupPermissions['wbeditor']['item-update']      = true; $wgGroupPermissions['wbeditor']['item-set']         = true; $wgGroupPermissions['wbeditor']['item-remove']      = true; $wgGroupPermissions['wbeditor']['alias-add']        = true; $wgGroupPermissions['wbeditor']['alias-update']     = true; $wgGroupPermissions['wbeditor']['alias-set']        = true; $wgGroupPermissions['wbeditor']['alias-remove']     = true; $wgGroupPermissions['wbeditor']['site-link-add']    = true; $wgGroupPermissions['wbeditor']['site-link-update'] = true; $wgGroupPermissions['wbeditor']['site-link-set']    = true; $wgGroupPermissions['wbeditor']['site-link-remove'] = true; $wgGroupPermissions['wbeditor']['lang-attr-add']    = true; $wgGroupPermissions['wbeditor']['lang-attr-update'] = true; $wgGroupPermissions['wbeditor']['lang-attr-set']    = true; $wgGroupPermissions['wbeditor']['lang-attr-remove'] = true;
 * Default setup

$wgGroupPermissions['*']['item-add']                = true; $wgGroupPermissions['*']['item-update']             = true; $wgGroupPermissions['*']['item-set']                = true; $wgGroupPermissions['wbeditor']['item-remove']      = true; $wgGroupPermissions['*']['alias-add']               = true; $wgGroupPermissions['*']['alias-update']            = true; $wgGroupPermissions['*']['alias-set']               = true; $wgGroupPermissions['wbeditor']['alias-remove']     = true; $wgGroupPermissions['*']['site-link-add']           = true; $wgGroupPermissions['*']['site-link-update']        = true; $wgGroupPermissions['*']['site-link-set']           = true; $wgGroupPermissions['wbeditor']['site-link-remove'] = true; $wgGroupPermissions['*']['lang-attr-add']           = true; $wgGroupPermissions['*']['lang-attr-update']        = true; $wgGroupPermissions['*']['lang-attr-set']           = true; $wgGroupPermissions['wbeditor']['lang-attr-remove'] = true;
 * Alternate setup

Mode
All call to content changing API functions should be developed for (and prepared to) use the POST mode. During development it is possible to allow use of GET to make it simpler to piece together working requests. Javascript code for the browser should always use POST requests. By enabled the setting apiInDebug, that is to set it to true, the enforced use of POST is turned off.

If the API is in debug mode, that is by setting apiInDebug to true, all GET requests will be accepted. The rejection of GET requests are reenabled by setting apiDebugWithPost to true. A production environment could allow use of GET requests, but note that GET requests could create problems with caching.

Setup

 * apiInTest : Turns test mode on. Default is undefined. (Not in Use)
 * apiInDebug : Turns debug mode on. Default is undefined.
 * apiInDebugWithRights : Enforce use of rights during debug. Has no effect when apiInDebug is not set. Default is true.
 * apiInDebugWithPost : Enforce use of POST requests during debug. Has no effect when apiInDebug is not set. Default is true.
 * apiInDebugWithRights : Enforce use of rights during debug. Has no effect when apiInDebug is not set. Default is true.
 * apiUseKeys : Enforce use of objects with keys when the module otherwise returns indexed arrays. Only affects json and json-like formats. Overrides "usekeys" in the url. Default is false, and should not be changed in production.

Normalization
Titles used in sitelinks can be normalized to give the same results as on a normal wiki. Sites are not normalized as they must comply to the list of accepted names.


 * Example : http://localhost/repo/api.php?action=wbsetlanguageattribute&site=de&title=_Wikimedia__&language=de&description=The%20conference%20for%20Wikimedia&item=update&format=jsonfm
 * Returns the identifier for the changed item

{ 	"item": { "descriptions": { "de": { "language": "de", "value": "The conference for Wikimedia" } 		}, 		"id": 3, "normalized": { "from": "_Wikimedia__", "to": "Wikimedia" } 	}, 	"success": 1 }

Saved values can also be normalized, but the stored values are reported back. If they are changed the reported value should be accurate.

Errors
If the error condition is prepared and expected, and a format is defined, the error messages will have a standardized form.

{ 	"servedby": "srv273", "error": { "code": "unknown_action", "info": "Unrecognized value for parameter 'action': blah" } }
 * example : http://localhost/repo/api.php?action=blah&format=jsonfm

The servedby is given unconditionally for error messages, but could be missing for some less than fatal errors. In some cases error messages can be appended to a success and be called warning(s).

All error messages from the Wikibase modules should be internationalized (i18n) and localized (l10n), but note that error messages from the base API system will usually not be localized. The user language for the logged in user (usually the same as in the web interface) will be the default for error messages. This can be overridden by putting uselang in the URL.

Do not depend on the info string for testing, use the code as this will remain independent of localization.

An internationalized error message that isn't localized as it should will have additional angle brackets.

{ 	"error": { "code": "no-such-item", "info": "&lt;wikibase-api-no-such-item&gt;" } }
 * example : http://localhost/repo/api.php?action=wbgetitemid&title=ThisPageDoesNotExist&site=fi&format=jsonfm

With correctly localized error message the angle brackets will go away and the info string will print out in clear text. Assuming the user is logged in and use English language it will print as something like the following.

{ 	"error": { "code": "no-such-item", "info": "There are no such item to be found" } }

Switching to Norwegian in the Special:Preferences or by appending  it will change the text of the info string to a localized variant, while the code string remains constant.

{ 	"error": { "code": "no-such-item", "info": "Det finnes ingen slik item" } }

A lot of error messages are not properly localized.

Success
If a success is achieved it will have the following form when the  is set ([//labs.wikimedia.org/w/api.php?action=wbgetitem&format=jsonfm labs], localhost)

{ 	"success": /* int */ }

The interpretation of the value for success can be dependent on the actual parameters in the call, but usually it is a boolean that is type casted to an integer. Its meaning is that every previous tests evaluated to true. If the number is 0 (zero) any additional values might be wrong.

There might be additional values in the structure after a successful call.