Extension:Wikibase Repository/API

Historical versions API1, API2, API3, API4.

Please see d:api.php for a perfectly up to date copy.

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. In the examples below the requests are shown as GET, but that will only work when debugging is turned on.

Modules

There are some parameters that are 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 entity or entities, most typical an item. Plural form is used in wbgetentities.

site ∩ title | sites ∩ titles 

Identifies a single item or multiple items. Plural form is used in wbgetentities. 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.

summary 

Adds a user specified summary instead of the system generated one. If not provided the module will generate its own summary, and if this fails the item itself will provide a summary.

token 

An encrypted string the requester must pass on shall the request be fullfilled.

revision 

An id for the last known revision that must be passed on shall the server be able to detect edit collisions.

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.

wbgetentities

Module to get the content of several entities, possibly with only parts of the entity included. Entities that are checked for existence, but not found, are reported (bugzilla:45509). During lookup both sites and titles can be a list, that is if the entities are items, but the shorter one is cycled to match the longer one. If one of the lists contain a single entry it will be used for all entries from the other list. If both lists are equally long the sitelinks will be well-formed pairs.

getItems/getEntities( ( ids XOR ( sites, titles ) ), *props, *languages )

• ids are numeric identifiers for existing entities, if the entities does not exist they will be marked as missing.
• sites ∩ titles is pairs that identifies multiple existing entities (only items), if they do not exist they will be marked as missing.
• props which list to report, possibly filtered by language if they are language specific. Possible values are labels, descriptions, sitelinks, claims. 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.

Example of general lookup with id 

api.php?action=wbgetentities&ids=Q42&format=jsonfm

{
	"entities": {
		"q42": {
			"id": "q42",
			"revision": 31186,
			"timestamp": "20120716140702",
			"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 limited lookup with site-title pair

api.php?action=wbgetentities&sites=enwiki&titles=Death_Star&props=labels&languages=nn&format=jsonfm

{
	"entities": {
		"q42": {
			"id": "q42",
			"revision": 31186,
			"timestamp": "20120716140702",
			"labels": {
				"nn": {
					"language": "nn",
					"value": "Dødsstjerna"
				}
			}
		}
	},
	"success": 1
}

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 ) ) OR baserevid, 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.
• baserevid is the page revision to use for further processing. Will be used for lookup of the item if id or site and title fails.
• 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.

Example with use of site-title pair 

api.php?action=wbsetsitelink&site=nowiki&title=Foo&linksite=nowiki&linktitle=Bar&format=jsonfm

{
	"item": {
		"sitelinks": {
			"nowiki": {
				"site": "nowiki",
				"title": "Bar"
			}
		},
		"id": 42,
		"lastrevid": 31186
	},
	"success": 1
}

Example with use of id 

api.php?action=wbsetsitelink&id=q42&linksite=nowiki&linktitle=Foo&format=jsonfm

{
	"item": {
		"sitelinks": {
			"nowiki": {
				"site": "nowiki",
				"title": "Foo"
			}
		},
		"id": 42,
		"lastrevid": 31187
	},
	"success": 1
}

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 ) ) OR baserevid, ( 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.
• baserevid is the page revision to use for further processing. Will be used for lookup of the item if id or site and title fails.
• 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.

Example changing label 

api.php?action=wbsetlanguageattribute&id=q42&language=en&label=Cyberdyne&format=jsonfm

{
	"item": {
		"labels": {
			"en": {
				"language": "en",
				"value": "Cyberdyne"
			}
		},
		"id": 42,
		"lastrevid": 31186
	},
	"success": 1,
}

Example changing description 

api.php?action=wbsetlanguageattribute&id=2&language=sv&description=Place%20where%20Alice%20lived%20for%20a%20short%20time&format=jsonfm

{
	"item": {
		"descriptions": {
			"sv": {
				"language": "sv",
				"value": "Place where Alice lived for a short time"
			}
		},
		"id": 2,
		"lastrevid": 31186
	},
	"success": 1
}

Example removing label 

api.php?action=wbsetlanguageattribute&id=q42&language=en&label=&format=jsonfm

{
	"item": {
		"labels": {
			"en": {
				"language": "en",
				"removed": ""
			}
		},
		"id": 42,
		"lastrevid": 31186
	},
	"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 ) ) OR baserevid, ( 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.
• baserevid is the page revision to use for further processing. Will be used for lookup of the item if id or site and title fails.
• 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.

Example set Foo and Bar 

api.php?action=wbsetaliases&language=en&id=q5&set=Foo|Bar&format=jsonfm

{
	"success": 1,
	"item": {
		"aliases": {
			"en": [
				{
					"language": "en",
					"value": "Foo"
				},
				{
					"language": "en",
					"value": "Bar"
				}
			]
		},
		"id": 42,
		"lastrevid": 31186
	}
}

Example add Test 

api.php?action=wbsetaliases&language=en&id=q5&add=Test&format=jsonfm

{
	"success": 1,
	"item": {
		"aliases": {
			"en": [
				{
					"language": "en",
					"value": "Foo"
				},
				{
					"language": "en",
					"value": "Bar"
				},
				{
					"language": "en",
					"value": "Test"
				}
			]
		},
		"id": 42,
		"lastrevid": 31186
	}
}

Example remove Foo and Test 

api.php?action=wbsetaliases&language=en&id=q5&remove=Foo|Test&format=jsonfm

{
	"success": 1,
	"item": {
		"aliases": {
			"en": [
				{
					"language": "en",
					"value": "Bar"
				}
			]
		},
		"id": 42,
		"lastrevid": 31186
	}
}

wbeditentity

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. Especially note that the behavior of calls with empty or missing data can change. Also note that the only expected behavior is creation of new empty items.

getItems( ( id XOR ( site, title ) ) OR baserevid, data, *clear, *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.
• baserevid is the page revision to use for further processing. Will be used for lookup of the item if id or site and title fails.
• clear is a marker to clear out the complete item and start from scratch.
• summary is a user entered string that is used in addition to an autocomment generated by the module itself.

Example deletion of item [undocumented behavior]

api.php?action=wbeditentity&id=q42&data=&format=jsonfm

Empty an existing item, a minimum item is not defined, but it is likely that an item that is "empty" will be deleted during later processing.

Example creation of empty object 

api.php?action=wbeditentity&new=item&data={}&format=jsonfm

Builds an "empty" item if not given an id, a minimum item is not defined, but it is likely that an item that is "empty" will be deleted during later processing.

{
	"item": {
		"id": 42,
		"lastrevid": 31186,
	},
	"success": 1
}

Example creates a prefilled item [undocumented behavior]

api.php?action=wbeditentity&data={%22labels%22:{%22de%22:%22Kopenhagen%22,%22en%22:%22Copenhagen%22}}&format=jsonfm

Builds an item with a few labels set, then returns the structure.

{
	"item": {
		"id": 42,
		"lastrevid": 31186,
		"labels": {
			"de": {
				"language": "de",
				"value": "Kopenhagen"
			},
 			"en": {
				"language": "en",
				"value": "Copenhagen"
			}
		}
	},
	"success": 1
}

Example modifies an existing item [undocumented behavior]

api.php?action=wbeditentity&id=q42&data={%22sitelinks%22:{%22nowiki%22:%22København%22,%22svwiki%22:%22Köpenhamn%22}}&format=jsonfm

Extends an item with a few sitelinks set, then returns the new structure.

{
	"item": {
		"id": 42,
		"lastrevid": 31186,
		"labels": {
			"de": {
				"language": "de",
				"value": "Kopenhagen"
			},
 			"en": {
				"language": "en",
				"value": "Copenhagen"
			}
		},
		"sitelinks": {
			"dewiki": {
				"site": "nowiki",
				"title": "København"
			},
 			"enwiki": {
				"site": "svwiki",
				"title": "Köpenhamn"
			}
		}
	},
	"success": 1
}

Note that setting sitelinks through this module bypasses normalization and verification. It is the sole responsibility of the user to do normalization and verification of the links before they are used.

New long format

This is examples of the new long format. This is closer to the internal representation and includes additional operations.

To make it easier to reuse information from other calls the structure in the request is (will be) made closer to the reply. Simple method-like requests will still be available as specific actions like wbsetlabel, wbsetdescription, wbsetaliases and wbsetsitelink. The changes are basically a shift from key-value pairs where the value is a single string, to a composite value that is an array. This will then contain the different parts and also possibly special actions. That complex structure is repeated for each value. Each of the repeated structures must also be according to the key if there is one, but it can be dismissed and the structures embedded in an array.

Note that the data arg {"labels":{"en":{"language":"en","value":"Foo"},"no":{"language":"no","value":"Bar"}}} and {"labels":[{"language":"en","value":"Foo"},{"language":"no","value":"Bar"}]} will produce the same effect on the stored values for labels, and similar {"descriptions":{"en":{"language":"en","value":"This is foo"},"no":{"language":"no","value":"This is bar"}}} and {"descriptions":[{"language":"en","value":"This is foo"},{"language":"no","value":"This is bar"}]} will produce the same effect on the stored values for descriptions.

There are to modifying operators that can be added as flags to the stored values. Those are add and remove. Setting them for individual elements will add or remove them, while not using them will be an overwrite operation. These operations/flags can be removed!

Define a simple item 

Its not necessary to add flags for adding/setting, but adding in this context means overwriting the existing value.

api.php?action=wbeditentity&id=q1&data={"labels":{"en":{"language":"en","value":"Foo"}},"descriptions":{"en":{"language":"en","value":"This%20is%20a%20text"}}}&format=jsonfm

api.php?action=wbeditentity&id=q1&data={"labels":[{"language":"en","value":"Foo"}],"descriptions":[{"language":"en","value":"This%20is%20a%20text"}]}&format=jsonfm

{
	"item": {
		"labels": {
			"en": {
				"language": "en",
				"value": "Foo"
			}
		},
		"descriptions": {
			"en": {
				"language": "en",
				"value": "This is a text"
			}
		}
		"id": 2,
		"lastrevid": 6065
	}
}

Add a label 

Its not necessary to add flags for adding/setting, but adding in this context means overwriting the existing value.

api.php?action=wbeditentity&id=q1&data={"labels":{"no":{"language":"no","value":"Bar"}}}&format=jsonfm

api.php?action=wbeditentity&id=q1&data={"labels":{"no":{"language":"no","value":"Bar","add":""}}}&format=jsonfm

api.php?action=wbeditentity&id=q1&data={"labels":[{"language":"no","value":"Bar"}]}&format=jsonfm

api.php?action=wbeditentity&id=q1&data={"labels":[{"language":"no","value":"Bar","add":""}]}&format=jsonfm

{
	"item": {
		"labels": {
			"en": {
				"language": "en",
				"value": "Foo"
			}
			"no": {
				"language": "no",
				"value": "Bar"
			}
		},
		"descriptions": {
			"en": {
				"language": "en",
				"value": "This is a text"
			}
		}
		"id": 1,
		"lastrevid": 6065
	}
}

Remove a label 

The label is removed if it is empty, and it is also removed if the "remove" flag is set. In the later case the actual value is neglected.

api.php?action=wbeditentity&id=q1&data={"labels":{"en":{"language":"en","value":""}}}&format=jsonfm

api.php?action=wbeditentity&id=q1&data={"labels":{"en":{"language":"en","value":"Foo","remove":""}}}&format=jsonfm

api.php?action=wbeditentity&id=q1&data={"labels":[{"language":"en","value":""}]}&format=jsonfm

api.php?action=wbeditentity&id=q1&data={"labels":[{"language":"en","value":"Foo","remove":""}]}&format=jsonfm

{
	"item": {
		"labels": {
			"no": {
				"language": "no",
				"value": "Bar"
			}
		},
		"descriptions": {
			"en": {
				"language": "en",
				"value": "This is a text"
			}
		}
		"id": 1,
		"lastrevid": 6065
	}
}

Aliases 

The aliases are a list, but there are still single values in each object structure. All values with the same operation for the same language will be added, removed or set as one operation. The set operations are those without an explicit add' or remove flag.

api.php?action=wbeditentity&id=q5&data={"aliases":{"en":[{"language":"en","value":"A"},{"language":"en","value":"B"},{"language":"en","value":"C"}]}}&format=jsonfm

api.php?action=wbeditentity&id=q5&data={"aliases":[{"language":"en","value":"A","add":""},{"language":"en","value":"B","add":""},{"language":"en","value":"C","add":""}]}&format=jsonfm

api.php?action=wbeditentity&id=q5&data={"aliases":[{"language":"en","value":"A"},{"language":"en","value":"B"},{"language":"en","value":"C"}]}&format=jsonfm

api.php?action=wbeditentity&id=q5&data={"aliases":{"en":[{"language":"en","value":"A"},{"language":"en","value":"B"},{"language":"en","value":"C"}]}}&format=jsonfm

api.php?action=wbeditentity&id=q1&data={"aliases":{"en":{"language":"en","value":"B","remove":""}}}&format=jsonfm

{
	"item": {
		"labels": {
			"no": {
				"language": "no",
				"value": "Bar"
			}
		},
		"descriptions": {
			"en": {
				"language": "en",
				"value": "This is a text"
			}
		},
		"aliases": {
			"en": [
				{
					"language": "en",
					"value": "A"
				},
				{
					"language": "en",
					"value": "B"
				},
				{
					"language": "en",
					"value": "C"
				}
			]
		},
		"id": 1,
		"lastrevid": 6065
	}
}

Add sitelinks

api.php?action=wbeditentity&id=q1&data={"sitelinks":{"enwiki":{"site":"enwiki","title":"Berlin"}}}&format=jsonfm

api.php?action=wbeditentity&id=q1&data={"sitelinks":{"enwiki":{"site":"enwiki","title":"Berlin","add":""}}}&format=jsonfm

api.php?action=wbeditentity&id=q5&data={"sitelinks":[{"site":"enwiki","title":"Berlin"}]}&format=jsonfm

api.php?action=wbeditentity&id=q5&data={"sitelinks":[{"site":"enwiki","title":"Berlin","add":""}]}&format=jsonfm

{
	"item": {
		"labels": {
			"no": {
				"language": "no",
				"value": "Bar"
			}
		},
		"descriptions": {
			"en": {
				"language": "en",
				"value": "This is a text"
			}
		},
		"aliases": {
			"en": [
				{
					"language": "en",
					"value": "A"
				},
				{
					"language": "en",
					"value": "C"
				}
			]
		},
		"sitelinks": {
			"enwiki": {
				"site": "enwiki",
				"title": "Berlin"
			}
		},
		"id": 1,
		"lastrevid": 6065
	}
}

Remove sitelinks

api.php?action=wbeditentity&id=q1&data={"sitelinks":{"enwiki":{"site":"enwiki","title":""}}}&format=jsonfm

api.php?action=wbeditentity&id=q1&data={"sitelinks":{"enwiki":{"site":"enwiki","title":"Berlin","remove":""}}}&format=jsonfm

api.php?action=wbeditentity&id=q5&data={"sitelinks":[{"site":"enwiki","title":""}]}&format=jsonfm

api.php?action=wbeditentity&id=q5&data={"sitelinks":[{"site":"enwiki","title":"Berlin","remove":""}]}&format=jsonfm

{
	"item": {
		"labels": {
			"no": {
				"language": "no",
				"value": "Bar"
			}
		},
		"descriptions": {
			"en": {
				"language": "en",
				"value": "This is a text"
			}
		},
		"aliases": {
			"en": [
				{
					"language": "en",
					"value": "A"
				},
				{
					"language": "en",
					"value": "C"
				}
			]
		},
		"id": 1,
		"lastrevid": 6065
	}
}

wbcreateclaim

• entity is the id of the entity you are adding the claim to
• snaktype (value, novalue, somevalue)
• property is the id of the snaks property
• value of snak when creating a claim with a snak that has a value
• baserevid is the page revision to use for further processing. Will be used for lookup of the item if id or site and title fails.

Add a claim with a string data value:

'action' => 'wbcreateclaim',
'entity' => 'q82',
'property' => 'p4',
'snaktype' => 'value',
'value' => '"Cyqi3STlJtEJ"',
'bot' => 1,

Add a claim with a wikibase-item data value:

'action' => 'wbcreateclaim',
'entity' => 'q82',
'property' => 'p2',
'snaktype' => 'value',
'value' => '{"entity-type":"item","numeric-id":63}',
'bot' => 1,

Add a claim with a time data value:

'action' => 'wbcreateclaim',
'entity' => 'q82',
'property' => 'p11',
'snaktype' => 'value',
'value' => '{"time":"+00000002010-01-02T00:00:00Z","timezone":0,"before":0,"after":0,"precision":11,"calendarmodel":"http://www.wikidata.org/entity/Q1985727"}',
'bot' => 1,

Add a claim with a globe-coordinate data value:

Note: value parameters "globe" and "precision" are optional. Default for "globe" is "http://www.wikidata.org/entity/Q2" (earth).

'action' => 'wbcreateclaim',
'entity' => 'q9188',
'property' => 'p625',
'snaktype' => 'value',
'value' => '{"latitude":40.748433,"longitude":-73.985656,"globe":"http://www.wikidata.org/entity/Q2"}',
'bot' => 1,

wbgetclaims

Module for getting Wikibase claims.

• entity is Id of the entity from which to obtain claims.
• property is optional filter to only return claims with a main snak that has the specified property.
• claim a GUID identifying the claim. Required unless entity is provided.
• rank is optional filter to return only the claims that have the specified rank. (deprecated, normal, preferred)
• props which list to report, possibly filtered by language if they are language specific. Note that sitelinks are not language specific.
• baserevid is the page revision to use for further processing. Will be used for lookup of the item if id or site and title fails.

Example of general lookup with id 

api.php?action=wbgetclaims&entity=q42&format=json

wbremoveclaims

Module for removing Wikibase claims.

• claim a GUID identifying the claim.
• baserevid is the page revision to use for further processing. Will be used for lookup of the item if id or site and title fails.

Example of removing a claim with a GUID 

api.php?action=wbremoveclaims&claim=q42$D8404CDA-25E4-4334-AF13-A3290BCD9C0N&token=foobar&baserevid=7201010

wbsetclaimvalue

Module for setting the value of a Wikibase claim.

• claim a GUID identifying the claim. Required.
• snaktype (value, novalue, somevalue).
• value of snak when setting a claim with a snak that has a value.
• baserevid is the page revision to use for further processing. Will be used for lookup of the item if id or site and title fails.

Example of setting a claim with GUID 

api.php?action=wbsetclaimvalue&claim=q42$D8404CDA-25E4-4334-AF13-A3290BCD9C0F&snaktype=value&value={"entity-type":"item","numeric-id":1}&token=foobar&baserevid=7201010

wbsetreference

Module for creating a reference or setting the value of an existing one.

• statement a GUID identifying the statement. Required.
• snaks FIXME.
• reference a hash of the reference that should be updated.
• baserevid is the page revision to use for further processing. Will be used for lookup of the item if id or site and title fails.

action:wbsetreference
format:json
statement:q76$D4FDE516-F20C-4154-ADCE-7C5B609DFDFF
snaks:{"p143":[{"snaktype":"value","property":"p143","datavalue":{"type":"wikibase-entityid","value":{"entity-type":"item","numeric-id":11696}}}]}
baserevid:779
token:+\

action:wbsetreference
format:json
statement:q76$D4FDE516-F20C-4154-ADCE-7C5B609DFDFF
snaks:{"p39":[{"snaktype":"value","property":"p14","datavalue":{"type":"string","value":"wikipedia"}}}
baserevid:779
token:+\

wbremovereferences

Module for removing one or more references of the same statement.

• statement a GUID identifying the statement. Required.
• references a hash of the reference that should be updated.
• baserevid is the page revision to use for further processing. Will be used for lookup of the item if id or site and title fails.

Example of removing a reference with hash from claim with GUID 

api.php?action=wbremovereferences&statement=q42$D8404CDA-25E4-4334-AF13-A3290BCD9C0F&references=455481eeac76e6a8af71a6b493c073d54788e7e9&token=foobar&baserevid=7201010

wbremovequalifiers

Module for removing a qualifier from a claim.

• claim a GUID identifying the claim. Required.
• qualifiers a hash of the qualifier that should be removed.
• baserevid is the page revision to use for further processing. Will be used for lookup of the item if id or site and title fails.

Remove qualifier with hash "1eb8793c002b1d9820c833d234a1b54c8e94187e" from claim with GUID of "q42$D8404CDA-25E4-4334-AF13-A3290BCD9C0F" 

api.php?action=wbremovequalifiers&statement=q42$D8404CDA-25E4-4334-AF13-A3290BCD9C0F&references=1eb8793c002b1d9820c833d234a1b54c8e94187e

wbsetqualifier

Module for creating a qualifier or setting the value of an existing one.

In this example, p4 is a string property:

'format' => 'json',
'action' => 'wbsetqualifier',
'claim' => 'q2$4554c0f4-47b2-1cd9-2db9-aa270064c9f3',
'property' => 'p4',
'value' => '"GdyjxP8I6XB3"',
'snaktype' => 'value',
'token' => 'f18s833ctn49799614c4o747521237c27+\\'

Add a qualifier with a wikibase-item data value:

'format' => 'json',
'action' => 'wbsetqualifier',
'claim' => 'q2$4554c0f4-47b2-1cd9-2db9-aa270064c9f3',
'property' => 'p2',
'snaktype' => 'value',
'value' => '{"entity-type":"item","numeric-id":63}',
'token' => 'f18s833ctn49799614c4o747521237c27+\\'

Add a qualifier with a time data value:

'format' => 'json',
'action' => 'wbsetqualifier',
'claim' => 'q102865$94797627-7ec6-47fd-9207-b615ccd682eb',
'property' => 'p580',
'snaktype' => 'value',
'value' => '{"time":"-00000000363-01-01T00:00:00Z","timezone":0,"before":0,"after":0,"precision":9,"calendarmodel":"http://www.wikidata.org/entity/Q1985727"}',
'token' => 'f18s833ctn49799614c4o747521237c27+\\'

wbsearchentities

Module to search for entities.

• search is the text string to search for
• language is the language to search in
• type is the type of entities to return
• limit is the maximum number of results to return (default 7)
• continue offset to continue the query from a previous search

Search for "abc" in English language, with defaults for type and limit 

api.php?action=wbsearchentities&search=abc&language=en&format=jsonfm

Search for "abc" in English language with a limit of 2 

api.php?action=wbsearchentities&search=abc&language=en&limit=2&format=jsonfm

{
    "searchinfo": {
        "search": "abc"
    },
    "search": [
        {
            "id": "q169889",
            "url": "//www.wikidata.org/wiki/Q169889",
            "description": "American broadcast television network",
            "label": "American Broadcasting Company",
            "aliases": [
                "ABC"
            ]
        },
        {
            "id": "q486289",
            "url": "//www.wikidata.org/wiki/Q486289",
            "description": "anarchist support organization",
            "label": "Anarchist Black Cross",
            "aliases": [
                "ABC"
            ]
        },
    ],
    "search-continue": 2,
    "success": 1
}

Search for "alphabet" in English language for type property 

api.php?action=wbsearchentities&search=alphabet&language=en&type=property&format=jsonfm

wbsetlabel

Module to set a label for a single Wikibase entity.

• 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.
• baserevid is the page revision to use for further processing. Will be used for lookup of the item if id or site and title fails.
• summary is a user entered string that is used in addition to an autocomment generated by the module itself.
• language is the language for the label. The language must be a valid identifier.
• value is the value of the label

Set the string "Wikimedia" for page with id "Q42" as a label in English language 

api.php?action=wbsetlabel&id=Q42&language=en&value=Wikimedia

Set the English language label to "Earth" for the item with site link enwiki => "Earth" 

api.php?action=wbsetlabel&site=enwiki&title=Earth&language=en&value=Earth

wbsetdescription

Module to set a description for a single Wikibase entity.

• 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.
• baserevid is the page revision to use for further processing. Will be used for lookup of the item if id or site and title fails.
• summary is a user entered string that is used in addition to an autocomment generated by the module itself.
• language is the language for the description. The language must be a valid identifier.
• value is the value of the description.

Set the string "An encyclopedia that everyone can edit" for page with id "Q42" as a decription in

English language : api.php?action=wbsetdescription&id=Q42&language=en&value=An%20encyclopedia%20that%20everyone%20can%20edit

Set the string "An encyclopedia that everyone can edit" as a decription in English language for

page with a sitelink to enwiki:Wikipedia : api.php?action=wbsetdescription&site=enwiki&title=Wikipedia&language=en&value=An%20encyclopedia%20that%20everyone%20can%20edit

wbsetclaim

Module for creating or updating an entire Claim.

• claim a claim in json form
• baserevid is the page revision to use for further processing. Will be used for lookup of the item if id or site and title fails.

Example 

api.php?action=wbsetclaim&claim={"id":"q2$5627445f-43cb-ed6d-3adb-760e85bd17ee","type":"claim","mainsnak":{"snaktype":"value","property":"p1","datavalue":{"value":"rand'.rand(1,100).'","type":"string"}}}&baserevid=9042&token=foobar

wblinktitles

Module to associate two articles on two different wikis with a Wikibase item.

• tosite ∩ totitle is pair that identifies first sitelink
• fromsite ∩ fromtitle is pair that identifies second sitelink

Add a link "Hydrogen" from the English page to "Wasserstoff" at the German page 

api.php?action=wblinktitles&fromsite=enwiki&fromtitle=Hydrogen&tosite=dewiki&totitle=Wasserstoff

wbsetstatementrank

To be defined.

wbmergeitems

Module to merge two Wikibase items.

• fromid is the numeric identifier for the item to merge from
• toid is the numeric identifier for the item to merge to

Example

api.php?action=wbmergeitems&fromid=Q1&toid=Q2

Deprecated

A number of modules are deprecated and will be removed.

wbgetsitelinks [deprecated]

Note this module is not supported anymore, use wbgetentities with props set to sitelinks.

wbdeletelanguageattribute [deprecated]

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

wblinksite [deprecated]

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

wbgetitemid [deprecated]

Note this module is not supported anymore, use wbgetentities with an empty props.

Data values

Time

Calendar model

• d:Q1985727 - Gregorian calendar
• d:Q1985786 - Julian calendar

Token

This is outdated, use an edit 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 any operation returns a new token it should be used for all following request. Do not assume that the itemtoken is the same as the edittoken.

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.

New tokens are in ver. 0.1 acquired by a request to any of the modules deriving from \Wikibase\Api.php, with gettoken in the URL.

Example using wbsetitem

api.php?action=wbsetitem&gettoken&format=jsonfm

{
        "wbsetitem": {
                "itemtoken": "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, possibly for each item, and update it for each expensive call so serialization is enforced.

See also Manual:Edit token.

Revision

The API uses revision ids for edit collision detection. If the revision id is known from an previous reply, page load or similar, then pass on the revision to the edit. Without the revision id it is not possible to detect edit collisions in a reliable way. If there is an edit collision the requester must acquire a newer revision id to be able to continue. This typically involves requesting wbgetentities for the item in question, and then storing (and using) the revision from the entry.

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 "props-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 'update 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

Default setup

$wgGroupPermissions['*']['item-override']		= true;
$wgGroupPermissions['*']['item-create']			= true;
$wgGroupPermissions['*']['item-remove']			= true;
$wgGroupPermissions['*']['alias-add']			= true;
$wgGroupPermissions['*']['alias-set']			= true;
$wgGroupPermissions['*']['alias-remove']		= true;
$wgGroupPermissions['*']['sitelink-remove']		= true;
$wgGroupPermissions['*']['sitelink-update']		= true;
$wgGroupPermissions['*']['label-remove']		= true;
$wgGroupPermissions['*']['label-update']		= true;
$wgGroupPermissions['*']['description-remove']		= true;
$wgGroupPermissions['*']['description-update']		= true;

Alternate setup

$wgGroupPermissions['*']['item-override']		= true;
$wgGroupPermissions['autoconfirmed']['item-create']	= true;
$wgGroupPermissions['wbeditor']['item-remove']		= true;
$wgGroupPermissions['*']['alias-add']			= true;
$wgGroupPermissions['wbeditor']['alias-set']		= true;
$wgGroupPermissions['*']['alias-remove']		= true;
$wgGroupPermissions['wbeditor']['sitelink-remove']	= true;
$wgGroupPermissions['*']['sitelink-update']		= true;
$wgGroupPermissions['wbeditor']['label-remove']		= true;
$wgGroupPermissions['*']['label-update']		= true;
$wgGroupPermissions['wbeditor']['description-remove']	= true;
$wgGroupPermissions['*']['description-update']		= true;

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.

Errors

Possible errors for all modules can be found at http://www.wikidata.org/w/api.php?action=paraminfo&modules=<modulename> eg. wbeditentity

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

example 

api.php?action=blah&format=jsonfm

{
	"servedby": "srv273",
	"error": {
		"code": "unknown_action",
		"info": "Unrecognized value for parameter 'action': blah"
	}
}

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.

example 

api.php?action=wbgetitemid&title=ThisPageDoesNotExist&site=fi&format=jsonfm

{
	"error": {
		"code": "no-such-item",
		"info": "<wikibase-api-no-such-item>"
	}
}

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 uselang=no 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

Can be removed since all normal calls will return data of some kind, unless there is an error condition.

If a success is achieved it will have the following form when the format=jsonfm is set (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.

See also

• API:Main page
• Manual:Maxlag parameter