Page MenuHomePhabricator

Show query parameters on Special:ApiSandbox as a JSON object, as well as a query string
Closed, ResolvedPublic

Description

Once you have build your query we give you a copyable URL:

But if you are using mw.Api to make your call, as many users will be, you'd want this data in JSON format. We could also provide it in PHP plain object format.

Event Timeline

Ricordisamoa renamed this task from Show query parameters as a JSON object (and others), as well as a query string to Show query parameters on Special:ApiSandbox as a JSON object (and others), as well as a query string.Mar 20 2016, 2:28 PM
Ricordisamoa added a subscriber: Ricordisamoa.
Anomie added a subscriber: Anomie.Mar 20 2016, 4:32 PM

You could as well make a case for Python (pywikibot), Perl, and every other
language in existence. Where is the line?

If you want to draw a line you could go with languages for which we provide a supported API in core.

But if you used a suitable UI component (e.g. dropdown) then I would have no objection to someone adding Python, Perl etc to that list.

JSON is JSON. JavaScript, Python, etc.

If you want to draw a line you could go with languages for which we provide a supported API in core.

So, none? Because the action API itself doesn't support any languages, it just supports input via HTTP GET or POST and provides output in a few different formats that can be parsed in many languages.

But if you used a suitable UI component (e.g. dropdown) then I would have no objection to someone adding Python, Perl etc to that list.

I would, because it's a bunch of additional complexity needed for something of rather limited utility.

I think it would be useful to show them formatted as JSON. JSON is not generally compatible with specific languages' syntax (even for JavaScript our coding conventions suggest different formatting of the quotes), but it's generally very easy to adjust with some search-and-replace.

Ricordisamoa renamed this task from Show query parameters on Special:ApiSandbox as a JSON object (and others), as well as a query string to Show query parameters on Special:ApiSandbox as a JSON object, as well as a query string.Apr 6 2016, 4:52 AM
Ricordisamoa updated the task description. (Show Details)
Legoktm added a subscriber: Legoktm.Apr 6 2016, 5:06 AM

Chromium dev tools has a option called "copy as CURL" in the network pane, which is a comparable feature. And I think providing copy-paste examples that devs can directly use will provide a much better developer experience (I most certainly would use it).

You could as well make a case for Python (pywikibot), Perl, and every other
language in existence. Where is the line?

For Python, I think providing an example that uses the standard library (urllib.request) would be better, plus a link to other libraries/frameworks (https://www.mediawiki.org/wiki/API:Client_code#Python).

We can draw an arbitrary line by saying to be included as an example it has to be some ##% of API usage on the Wikimedia cluster.

jayvdb added a subscriber: jayvdb.Apr 6 2016, 6:01 AM

IMO any python example should use requests rather that Python version
specific code.

IMO any python example should use requests rather that Python version
specific code.

Requests means library-specific code, no matter how de facto standard it is ;-)

Anomie added a comment.Apr 6 2016, 3:14 PM

We can draw an arbitrary line by saying to be included as an example it has to be some ##% of API usage on the Wikimedia cluster.

Except there's no way to measure what programming language people are using to make their requests. Sometimes it's in User-Agent, but often enough it's not. Taking 161 agents that recently showed up in the api-feature-usage log as a random sample,

  • Only 16 seem to actually specify the language (and that's being generous about "specify", e.g. "WikibasePhpLib" mentions PHP so that's close enough).
  • 18 more can be guessed because they mention a filename with a relevant extension (e.g. "foo.js" or "bar.py"). But deduplicating user scripts/gadgets using Api-User-Agent brings that down to only 5 unique agents.
  • 63 are generic browser-looking agents, but that doesn't necessarily mean they're actually JS from browsers.
  • 63 lack any reasonable indication of language, although for some you can guess with prior knowledge of what language the mentioned framework uses.
Tgr added a subscriber: Tgr.Dec 23 2016, 11:48 AM

Except there's no way to measure what programming language people are using to make their requests.

Maybe run a survey, or check what tags are used most often with MediaWiki-API on Stackoverflow?

In general, it could be handled by a hook or other pluggable method since it might depend on the audience of the wiki. For Wikimedia wikis mw.Api (for gadget writers) and jQuery (which seems to get the most beginner question on SO) are the most obvious contenders IMO.

Esanders added a comment.EditedDec 23 2016, 12:42 PM

If you want to draw a line you could go with languages for which we provide a supported API in core.

So, none? Because the action API itself doesn't support any languages, it just supports input via HTTP GET or POST and provides output in a few different formats that can be parsed in many languages.

Clearly I don't mean the API protocol itself, we all know that's HTTP. We have a JavaScript library in MW core for making API calls (mediawiki.api.js), and a PHP one (ApiBase.phpApiMain.php), so there is a sensible place to draw a line.

I think it would be useful to show them formatted as JSON. JSON is not generally compatible with specific languages' syntax (even for JavaScript our coding conventions suggest different formatting of the quotes), but it's generally very easy to adjust with some search-and-replace.

+1

and a PHP one (ApiBase.php)

ApiBase isn't a library for calling the API, it's the base class for implementing the API.

and a PHP one (ApiBase.php)

ApiBase isn't a library for calling the API, it's the base class for implementing the API.

Sorry, ApiMain.php is an implementation though.

and a PHP one (ApiBase.php)

ApiBase isn't a library for calling the API, it's the base class for implementing the API.

Sorry, ApiMain.php is an implementation though.

As in another class involved in implementing the API, not in calling it? Yes.

It can be invoked directly to make derivative requests, so users writing code in core may need PHP object params. Regardless, coming up with a concrete way to define what should be listed shouldn't be a blocker - don't make perfect the enemy of good.

Can, yes. Should? No.

Change 328900 had a related patch set uploaded (by Esanders):
ApiSandbox: Display params as JSON on request page

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

Proposed implementation:

BeforeAfter
matmarex closed this task as Resolved.Jan 3 2017, 8:37 PM
matmarex assigned this task to Esanders.
matmarex removed a project: Patch-For-Review.

We can deliberate on other formats later, but I think we're in agreement that JSON is neutral and definitely useful.

Change 328900 merged by jenkins-bot:
ApiSandbox: Display params as JSON on request page

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

matmarex removed a subscriber: matmarex.Jan 4 2017, 4:14 PM
matmarex closed this task as Resolved.Jan 4 2017, 10:40 PM

(Not actually reverted)