Re: [Wikitech-l] Reporting errors from the API
On 01/25/2013 08:01 AM, Daniel Kinzler wrote: > * 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. It you take the approach of clients rendering wikitext into HTML, you can use jqueryMsg (https://www.mediawiki.org/wiki/Manual:Messages_API#mediawiki.jqueryMsg) Of course, non MediaWiki clients will have to use the error code or some other string. Matt Flaschen ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] Reporting errors from the API
Speaking of which, where is the (if there is any) roadmap document or something similar for the next version of the API? *--* *Tyler Romeo* Stevens Institute of Technology, Class of 2015 Major in Computer Science www.whizkidztech.com | tylerro...@gmail.com On Fri, Jan 25, 2013 at 10:08 AM, Brad Jorsch wrote: > On Fri, Jan 25, 2013 at 9:48 AM, Tyler Romeo wrote: > >> > >> * Should error messages returned by the API be translated? Or should the > >> translation be left to JavaScript in the client? > > > > I think it should be left to JavaScript in the client. The API is not a > UI, > > so it is not intended to function as an internationalized interface. > > However, a JavaScript script that uses the API *is* part of a UI, and > thus > > has the burden of internationalizing whatever it does. Additionally, I > > don't know much about our API clients, but adding in non-ASCII characters > > may or may not cause issues. > > Any client that has issues with non-ASCII characters is probably > already broken, since our pages have non-ASCII all over the place and > non-ASCII can make its way into error messages by being included in > page titles and such. > > As for i18n, it would be nice to support API users that don't speak > English well. > > ___ > Wikitech-l mailing list > Wikitech-l@lists.wikimedia.org > https://lists.wikimedia.org/mailman/listinfo/wikitech-l > ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] Reporting errors from the API
On Fri, Jan 25, 2013 at 9:48 AM, Tyler Romeo wrote: >> >> * Should error messages returned by the API be translated? Or should the >> translation be left to JavaScript in the client? > > I think it should be left to JavaScript in the client. The API is not a UI, > so it is not intended to function as an internationalized interface. > However, a JavaScript script that uses the API *is* part of a UI, and thus > has the burden of internationalizing whatever it does. Additionally, I > don't know much about our API clients, but adding in non-ASCII characters > may or may not cause issues. Any client that has issues with non-ASCII characters is probably already broken, since our pages have non-ASCII all over the place and non-ASCII can make its way into error messages by being included in page titles and such. As for i18n, it would be nice to support API users that don't speak English well. ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] Reporting errors from the API
I'm going to copy this to the mediawiki-api list, too. On Fri, Jan 25, 2013 at 8:01 AM, Daniel Kinzler 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 API internationalized is probably either being passed through from something 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 error messages from the API. The problem is that if we want to do anything without waiting for "API version 2", we want to avoid as much as possible breaking backwards compatibility with existing clients. Which probably means that we'll want to add a parameter for the client to specify the new style errors and warnings; this can double as selecting the language the errors should be returned in. I'd have to look at what existing code does as far as errors/warnings before 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 in plain text, and should ''not'' use the MediaWiki namespace. In terms of the Message class, $msg->useDatabase( false )->text(). This makes things sensible for bots and such; they will often be writing errors to a log file or showing them in some user interface where HTML parsing is probably not available. The message key and parameters should (optionally?) be returned for the client to format as HTML or whatever. And the client is welcome to use the MediaWiki namespace. This is sensible for Javascript user interface and such. Unfortunately, it seems that the message key prefix "api-error-" is already 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 a convertStatusToArray() method. > Any thoughts on that? > > -- daniel ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] Reporting errors from the API
> > * Should error messages returned by the API be translated? Or should the > translation be left to JavaScript in the client? I think it should be left to JavaScript in the client. The API is not a UI, so it is not intended to function as an internationalized interface. However, a JavaScript script that uses the API *is* part of a UI, and thus has the burden of internationalizing whatever it does. Additionally, I don't know much about our API clients, but adding in non-ASCII characters may or may not cause issues. > ** In both cases, it would be nice to have a consistent relationship > between > error codes and the corresponding system message. I agree. Maybe for each error message in the api we have a "api-$code" message that corresponds to a proper description of the error. > > ** 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. Herein lies the biggest difficulty. *--* *Tyler Romeo* Stevens Institute of Technology, Class of 2015 Major in Computer Science www.whizkidztech.com | tylerro...@gmail.com On Fri, Jan 25, 2013 at 8:01 AM, Daniel Kinzler 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). > > 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. > > > * 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. > > * 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). > > Any thoughts on that? > > -- daniel > > ___ > Wikitech-l mailing list > Wikitech-l@lists.wikimedia.org > https://lists.wikimedia.org/mailman/listinfo/wikitech-l > ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
