Page MenuHomePhabricator

[Task] Merge on-wiki Wikibase/API documentation into Wikibase apihelp strings.
Open, NormalPublic

Description

https://www.mediawiki.org/wiki/Wikibase/API?oldid=1413489#Modules has old documentation (by addshore, aude, jeblad, ... from 2014) of most Wikibase API modules. We should kill it in favor of generated API documentation.

But if you compare, e.g. https://www.mediawiki.org/wiki/Wikibase/API#wbgetentities with https://www.wikidata.org/wiki/Special:ApiHelp/wbgetentities , the former has better introductory text and better explanation of parameters including the mysterious "sites ∩ titles" explanation. This should be merged into the apihelp-wbgetentities-* i18n messages to improve them. Likewise for the other 19 wikibase API modules.

Event Timeline

Spage raised the priority of this task from to Normal.
Spage updated the task description. (Show Details)
Spage added projects: Wikidata, Web-APIs-Hub.
Spage added subscribers: Christopher, Addshore, Lucie and 5 others.
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptFeb 18 2015, 7:19 PM

I think the biggest blocker here really is that it is hard to fit all of the information we want to into the current structure of documentation for api modules.

I mean this either comes down to:

  1. a lot of examples for every api module, but with large json blobs which are hard to read as they are not formatted...
  2. json blobs in param descriptions?
  3. json blobs in i18n messages

All of these are rather ugly imo....

@Anomie any suggestions? Or which would you choose?

Anomie added a comment.Sep 8 2015, 7:09 PM

JSON blobs in API parameters are generally ugly, which is why I always recommend against them.

The JSON blobs I see on the linked page are all parts of examples, so examples would be the way to go IMO. Or else what other JSON blobs are you referring to?

I am indeed talking about those JSON blobs.
For wikidata it would be nice to be able to also provide the json blobs that are used in the query strings as a pretty json blob so that people can actually read them!

As well as the string link and the description it might be nice to be able to also provide a pretty example.
I have no idea how this would all work tbh, but it is the only way I see of moving forward and making the wikidata api examples more readable.

The pretty-printed JSON I see on https://www.mediawiki.org/wiki/Wikibase/API#wbgetentities is all in the output from the examples, which will already be pretty-printed when the user actually clicks on it to see that output (e.g. here). Where JSON is occurring in the request URIs, I see no pretty-printing going on on that page.

I see some of the pseudo-examples don't even bother with a URI, and just show the query parameters as either a partial PHP array or partial JSON object format, but even there the JSON blobs being passed as parameters are strings rather than being pretty-printed.

Or are you trying to say you want to add pretty-printing to the JSON blobs in the URI parameters?

Well previous to the comment above I remember the example links having url encoded json, the fact that this is no longer the case is a big win!
This makes handling JSON in the example links much much better!

As for the results, yes in most cases people can simply click the link (although not the case for POST stuff which covers the majority of the api modules)
I don't know if there is really a nice solution for that at this stage.

As for the results, yes in most cases people can simply click the link (although not the case for POST stuff which covers the majority of the api modules)
I don't know if there is really a nice solution for that at this stage.

If https://gerrit.wikimedia.org/r/#/c/209570/ ever gets unblocked, a logical next step would be to somehow link examples there. There's already T89229: API Help should generate [try in ApiSandbox] link to Special:ApiSandbox#action=params from getExamples() asking for that.

Okay, that seems ideal.
So over the next week I will try and move all examples that are currently missing in the code from the wikipage!

Addshore set Security to None.
Jonas renamed this task from Merge on-wiki Wikibase/API documentation into Wikibase apihelp strings. to [Task] Merge on-wiki Wikibase/API documentation into Wikibase apihelp strings..Nov 2 2015, 3:24 PM
Addshore removed Addshore as the assignee of this task.Dec 2 2015, 11:27 AM