Page MenuHomePhabricator

Adjust expectations for API consumers when using the TextExtracts API
Closed, ResolvedPublic2 Story Points

Description

Caveats with the existing TextExtracts service are documented here:
https://www.mediawiki.org/wiki/Extension:TextExtracts#Caveats

We should also surface these in the API response as warnings where possible.

  • When exsentences is used in html mode a warning should be sent to the consumer "exsentences is not guaranteed to work when used in HTML mode."
  • In HTML mode for all output show a warning "HTML may be malformed and/or unbalanced and may omit inline images. Use at your own risk. Known problems are listed at https://www.mediawiki.org/wiki/Extension:TextExtracts#Caveats"
  • The message should be configurable via messages. WikimediaMessages for instance may want to point users to the alternative RESTBase service.

Questions

  • Should we also point them to the RESTbase service in these warning messages?

This is up to the wiki which can customise the message.

No: Let's keep the status quo. Changing how the extract behaves may interfere with how people are currently using the API and it provides little gain for ourselves.

Developer notes

You can add warnings like so when certain combos are used:

$this->addWarning( 'i18n-message-key' );

See T170617#4047560 for details.

Details

Related Gerrit Patches:

Related Objects

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJul 13 2017, 6:44 PM
Jdlrobson changed the task status from Open to Stalled.Jul 21 2017, 5:50 PM
Jdlrobson triaged this task as Medium priority.

I suggest we do this when the new endpoint is in place - that way we can decide if we want to add a URL for the new endpoint to the warning messages

Progress on T179875 has been made \o/

Anomie added a subscriber: Anomie.Jan 23 2018, 1:43 AM

Should we also point them to the RESTbase service in these warning messages?

Remember third party wikis exist and might have TextExtracts installed.

Yeh the idea is that this would be configurable and only updated for Wikimedia services. I've updated the description to make this clearer.

Jdlrobson changed the task status from Stalled to Open.Feb 22 2018, 10:07 PM

No longer stalled.

Krinkle updated the task description. (Show Details)Mar 13 2018, 2:06 AM

As part of this task, this work includes updating https://www.mediawiki.org/wiki/Reading/Component_responsibility to note "Non-security patches not reviewed."

Jdlrobson set the point value for this task to 2.Mar 13 2018, 4:18 PM
@Jdlrobson wrote:

You can add warnings like so when certain combos are used:

$main->addWarning( new RawMessage( 'existing warning' ), 'existing-warning' );

If you do that, I will be very unhappy with you. There's never a case where you should use a RawMessage with ->addWarning(), and you shouldn't call it on the ApiMain directly as implied by your specifying $main rather than $this.

The correct way is similar. First, see if one of the existing message keys beginning with "apiwarn-" can be used. If not, copy the warning text to the extension's i18n JSON files with an appropriate key.

Then the basic code to use is

// Simple case
$this->addWarning( 'i18n-message-key' );

// Pass an array to specify parameters for the message.
// Be sure to use `wfEscapeWikiText()` or `Message::plaintextParam()` on parameters that come from user input!
$this->addWarning( [ 'i18n-message-key', 'parameter1', 'etc' ] );

// By default, the machine-readable code for the warning (when `errorformat` is not `bc`) is the i18n message key
// with "apiwarn-" or "apierror-" removed from the beginning, if applicable. You can override that with the second
// parameter to ->addWarning()
$this->addWarning( 'i18n-message-key', 'code' );
$this->addWarning( [ 'i18n-message-key', 'parameter1', 'etc' ], 'code' );
Anomie updated the task description. (Show Details)Mar 13 2018, 6:42 PM
Jdlrobson added a comment.EditedMar 13 2018, 6:47 PM

Thank you for updating the description. I just copied and pasted and instance directly from core to help a conversation. I was just explaining the API has an addWarning method baked in, I was not suggesting the usage of RawMessage :) Thanks for providing some better examples.

Good, I'm glad it was just a bad copy-paste rather than a real recommendation. (: For examples of usage it's probably better to look in core API modules rather than in their unit tests.

Also, I see I was wrong. There's one case where RawMessage might be used: unit tests of warning handling. ;)

pmiazga claimed this task.Mar 20 2018, 4:26 PM
pmiazga moved this task from To Do to Doing on the Readers-Web-Kanbanana-Board-Old board.

Change 420753 had a related patch set uploaded (by Jdlrobson; owner: Jdlrobson):
[mediawiki/extensions/TextExtracts@master] Adjust expectations for API consumers when using the TextExtracts API

https://gerrit.wikimedia.org/r/420753

pmiazga reassigned this task from pmiazga to Jdlrobson.Mar 20 2018, 4:35 PM
pmiazga added a subscriber: pmiazga.

Change 420753 merged by jenkins-bot:
[mediawiki/extensions/TextExtracts@master] Adjust expectations for API consumers when using the TextExtracts API

https://gerrit.wikimedia.org/r/420753

This is technical task, moving directly to sign-off column. @Jhernandez @Jdrewniak @Niedzielski - ready for sign off -> can you double check it and resolve the task?