I'm going to copy this to the mediawiki-api list, too.On Fri, Jan 25, 2013 at 8:01 AM, Daniel Kinzler <daniel(a)brightbyte.de> wrote:> Hi all!>> Wikidata (technically, Wikibase) uses a lot of JS/API based editing, and we have> several times hit upon the question of how to best report errors from the API.> I'll try to break the issue down into several concrete questions. But first off,> the status quo as I understand it:>> * errors are reported using an error code (a string) and a free form error> message. The message is usually not internationalized, though sometimes it is.> * warnings are reported as free form text.> * Additional information can be added to both errors and warnings, but there is> no standard way to do this.> * Errors exposed by the API are often not generated but just passed through by> the API; Typically, a generic error code is used with the original error message> (e.g. from an exception).Sounds generally correct. Anything coming out of the APIinternationalized is probably either being passed through fromsomething else or being generated in an extension.> So, here are my questions:>> * Should error messages returned by the API be translated? Or should the> translation be left to JavaScript in the client?> ** In both cases, it would be nice to have a consistent relationship between> error codes and the corresponding system message.> ** If translation is done on the client, we need to pass any message parameters> separately.> ** The message key would have to somehow be derived or mapped from the error code.It would be nice to have internationalized and parameterized errormessages from the API. The problem is that if we want to do anythingwithout waiting for "API version 2", we want to avoid as much aspossible breaking backwards compatibility with existing clients. Whichprobably means that we'll want to add a parameter for the client tospecify the new style errors and warnings; this can double asselecting the language the errors should be returned in.I'd have to look at what existing code does as far as errors/warningsbefore making a more concrete proposal.> * When using system messages to translate the error codes from the API, these> messages will often contain wikitext. How can we best avoid this? Wikitext is> likely to be quite useless to the client - it would be better to return HTML; or> pass all the message keys and parameters, and let the client generate the message.I'd suggest that messages actually returned by the API should be inplain text, and should ''not'' use the MediaWiki namespace. In termsof the Message class, $msg->useDatabase( false )->text(). This makesthings sensible for bots and such; they will often be writing errorsto a log file or showing them in some user interface where HTMLparsing is probably not available.The message key and parameters should (optionally?) be returned forthe client to format as HTML or whatever. And the client is welcome touse the MediaWiki namespace. This is sensible for Javascript userinterface and such.Unfortunately, it seems that the message key prefix "api-error-" isalready in use.> * Status objects are often used to collect errors and warnings the occur while> trying to perform some task. It would be nice if the API would provide a> standard way to put the contents of a Status object into the result (well, at> least the errors and warnings).It seems it does, at least sort of: ApiResult has aconvertStatusToArray() method.> Any thoughts on that?>> -- daniel
