Extension:Wikibase Repository/API4

This is an experimental API ver. 4 for Wikidata, with focus on the API for the Repo. Its only for the Repo-part for now.

Core concepts

The API should be simplified and try to mimic accessors as close as possibly, but due to some inherent problems we want to avoid making a bloat of modules.

There are some similarities we will try to build upon, that was not readily visible in the first versions. Due to this we will reorganize the API around some core concepts

There is a generic get items module that reads from some kind of slow but stable back store.
There is an optimized get attribute (get item id) module that reads from some kind of fast but unstable front store. This is optimized for speed and returns single (?) key-value pairs. It could be necessary to handle failed lookups by checking the back store.
There is a set/change attribute (set description, set label, set alias) module that sets single attribute within the item that is changeable and has a one-to-one relationship with languages. To set an attribute to an empty or non-existing value imply that it will be removed. This module accesses the stable back store.
There is a remove/drop attributes (remove description, remove label, remove alias) module that removes multiple attributes within the item that is changeable and has a one-to-one relationship with languages. There can be given several attributes given at once. This module accesses the stable back store. (Not sure if this is really necessary as an empty value could imply a drop.)
There is a search by name module that uses the unstable front store.
The module for linksite is slightly different as it does not follow the key → language → value but a key → site → title. Could be a subkey that has language and site as alias.

Alias is a bit odd as it has a value that is both a key and a value, and can have several entries in each language. It will look like it should be a drop, while it should not.

Typically the slow but stable back store is something like MySQL or PostgreSQL. Subsystems that needs to maintain high data integrity should use this one. The fast but unstable front store could be something else. Subsystems that can handle data with low integrity should use this one as it would be very much faster.

It is important to notice that the optimized get attribute module can return invalid key-value pairs. Because of this the code must be able to unwind exceptions due to fails induced by this, even if it would happen very seldom.

1

The attribute modules takes two arguments to specify an item, but as this pairing is difficult for a many-to-many relationship in the lookup one of them has to be one, forcing it into a one-to-many relationship in the call. For example will lookup with the combination of site and title only be possible if one of the arrays contain a single value. The two alternate ways to do lookup for the attribute methods, that is id or the two site and title, are exclusive. It is an error use both lookup methods at the same time.

There is an argument key that says which attribute to return for the get modules or which to change or drop. A key can only take one name. If a key can work with languages the number of entries in this argument needs to be the same as in values for change operations. It is an error if the two arrays are of different length. An empty entry in the values entry imply a drop. For the drop module there should be no values defined. Additional values like badges must be in an array of similar length to the values.

Don't return more data than you need, returning to much will create an unnecessary system load.

examples

label & description

api.php?action=wbchangeattribute&id=42&prop=label&languages=no&value=Norge
api.php?action=wbchangeattribute&id=42&prop=label&languages=no|en&value=Norge|Norway
api.php?action=wbchangeattribute&id=42&prop=label&languages=no|en&value=Norge|Norway&summary=This%20is%20a%20test
api.php?action=wbchangeattribute&id=42&prop=label&languages=no&value=Norge
api.php?action=wbchangeattribute&id=42&prop=label&languages=no|en&value=|
api.php?action=wbchangeattribute&id=42&prop=label&languages=no|en&value=|&summary=This%20is%20a%20test
api.php?action=wbchangeattribute&id=42&prop=label&languages=no&remove
api.php?action=wbchangeattribute&id=42&prop=label&languages=no|en&remove
api.php?action=wbchangeattribute&id=42&prop=label&languages=no|en&remove&summary=This%20is%20a%20test