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?

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.

In T89863#1756444, @Addshore wrote:

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!