Extension:Wikibase Repository/API3
- Old versions: Extension:Wikibase/API1, Extension:Wikibase/API2
Additional API specification for Wikibase are additional description of how the API modules for Wikibase are supposed to behave, mostly with focus on how the server (where the Wikibase extension runs) is supposed to respond to requests from clients in general (where the Wikiclient extension runs) and browsers especially (where a Javascripts loaded by ResourceLoader). This is not a complete description, check the labs API's documentation (missing correct labs instance) for further details (just a dummy link, use localhost for now, later use labs).
Note that this documentation is not final and that it will change due to new or changed requirements from the project and its main objective. The projects main objectiveis to build the extension, interfacing with other tools are other secondary outcome. The main objectives for the API is close to the specific task and mobile friendly, ie. dense representation. As such this will be an attempt on a best practice for the API given contraints from other ducumentation and the API itself, but as the existing API are generic there must be made some trade offs due to responsiveness and code complexity.
General parameters
[edit]There are some general parameters that could be useful. Those are format, smaxage, maxage, maxlag and requestid. In the self documenting API all of them except format is described first on the page.
Parameter format is used to define the return format, usually always set to json for the extension but could also be set to xml for other tools. For debugging use the values jsonfm and xmlfm to get a pretty printed version. There are several other formats, check the documentation. Make sure that new modules in fact responds with the correct structure.
Parameter smaxage and maxage is used when interacting with caching. Do not set them unless it is clear that previous requests can be reused.
Parameter maxlag is used for throttling of requests, use longer times for more important requests. Setting this parameter will make it necessary to implement error handling.
Parameter requestid it can be used where several requests are handled in parallel. This can speed up interaction with the server.
General responses
[edit]Success
[edit]If a success is achieved it will have the following form when the format=jsonfm is set (labs, localhost)
{ "success": /* int */ }
- Note
- The interpretation of the value for success can be dependent on the actual parameters in the call.
- There might be additional values in the structure.
Normalization
[edit]No information about normalization (or redirects) will be returned.
- Note
- This can change in later versions.
Error
[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 (labs, localhost)
{ "servedby": "srv273", "error": { "code": "unknown_action", "info": "Unrecognized value for parameter 'action': blah" } }
- Note
- Note that servedby is given unconditionally for error messages.
- Note that a warning can be given by appending an error to a success.
Not implemented
[edit]Typical error message when some function of a module is not implemented and format=jsonfm is set (labs, localhost)
{ "error": { "code": "internal_api_error_MWException", "info": "Exception Caught: Internal error in ApiWikibaseGetItem::execute: Unhandled case value: ", "*": "\n" /* hidden stacktrace */ } }
Modules
[edit]wbgetitem
[edit]Should be called wbgetitems.
- Example
{ "page": { "sitelinks": [ { "language" : "en", "site" : "wikipedia", "value" : "Georgia_(country)" }, { "language" : "de", "site" : "wikipedia", "value" : "Georgien" } ], "labels" : { "en" : { "language" : "en", "value" : "Georgia", }, "de" : { "language" : "de", "de" : "Georgien" } }, "descriptions" : { "en" : { "language" : "en", "value" : "A central-asian country", }, "de" : { "language" : "de", "value" : "Land im Kaukasus" } } }, "success": /* boolean typecasted as int */ }
- Notes
- There might be none, one or many pages in the structure under pages.
- There might be none, one or many site links for a single language for each page.
Labels and descriptions are simple and unique language – string -pairs and is easier to handle without the convolved structure used for languages.There is pronunciation and other stuff that needs to be saven in addition.- The numeric item directly under pages is for the stable id, the pageid is added if its necessary.
- With only one page the page structure can be flattened one level.
wbgetitemid
[edit]{ "page": { "id": 42, }, "success": /* boolean typecasted as int */ }
- Notes
- There might be none or one page with a given stable id.
- A successful completion could return without an id, that is no page is found.
- This is the stable id, the pageid is added if its necessary.
- It could be argued that id should be wrapped in a structure page, and then the arguments from the lookup could be included as this avoids the use of .
- Alt 2 (not implemented)
{ "page": { "site": /* something */, "title": /* something */, "id": 42, }, "success": /* boolean typecasted as int */ }
wbsitelink
[edit]{ "success": /* boolean typecasted as int */ }
- Notes
- Return codes for success indicates if a new site link is added or if it already exists.
- This module needs edit rights.
wbremovesitelink
[edit]Should be called wbdropsitelink.
{ "success": /* int */ }
- Notes
- Return codes for success indicates if an exising site link is removed or if it never existed.
- This module needs edit rights.
wbsetdescription
[edit]The description is the localized name according to user languages on the internal (server) wiki page. The description can be edited for other languages and not only the users set user language. More about this in the section EntityDescriptions of Items and Properties at the background page m:Data model.
- Calling
- api-generated help (localhost)
- Result
{ "success": /* boolean typecasted as int */ }
- Notes
Return codes for success indicates if a new description is added or if it already exists and is updated.- Return codes for success indicates if the edit returned a status code of ok.
- Doing a set without a preexisting value will create it.
- This module needs edit rights.
wbremovedescription
[edit]Should be called wbdeletedescription. It is not clear if this should be merged with wbsetdescription.
{ "success": /* int */ }
- Notes
- Return codes for success indicates if an exising description is removed or if it never existed.
- This module needs edit rights.
wbsetlabel
[edit]The label is the localized name according to user language on the internal (server) wiki page. The label can be edited for other languages and not only the users set user language. More about this in the section EntityDescriptions of Items and Properties at the background page m:Data model.
- Calling
- api-generated help (localhost)
- Result
{ "success": /* boolean typecasted as int */ }
- Notes
Return codes for success indicates if a new label is added or if it already exists and is updated.- Return codes for success indicates if the edit returned a status code of ok.
- Doing a set without a preexisting value will create it.
- This module needs edit rights.
wbremovelabel
[edit]Should be called wbdeletelabel. It is not clear if this should be merged with wbsetlabel.
{ "success": /* int */ }
- Notes
- Return codes for success indicates if an existing label is removed or if it never existed.
- This module needs edit rights.