Page MenuHomePhabricator

[Story] Include example JSON blobs in API module descriptions
Open, MediumPublic

Description

Certain Wikibase API modules, e.g. SetClaim or SetReference, do have a field that must contain a JSON blob. Even if these API modules are not made to be used manually by a user, we want users to play around with the API and learn how it works. That's one of the reasons why we have the ApiSandbox.

Problem: It's not at all obvious how these JSON blobs should look like. Even if you try to copy and paste that JSON from a previous GetClaims request or an other source, you need to know which part of the JSON blob must be copied. What I currently do is looking at the actual PHP source of the API module plus a fair amount of trial and error.

Suggestion: Include a minimal example in the description. At least show the "header" of an example JSON blob so users can identify the required part(s) in a full entity blob. Warning: The example should not parse to avoid accidental copy-pastes. This can be achieved by replacing the "flesh" of the example with .

(Related, but independent task: T98458.)

Event Timeline

thiemowmde raised the priority of this task from to Needs Triage.
thiemowmde updated the task description. (Show Details)
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptMay 7 2015, 1:37 PM
Lydia_Pintscher triaged this task as Medium priority.May 15 2015, 2:01 PM
Lydia_Pintscher set Security to None.
Lydia_Pintscher added a subscriber: Lucie.
Jonas renamed this task from Include example JSON blobs in API module descriptions to [Story] Include example JSON blobs in API module descriptions.Aug 14 2015, 9:10 AM

Both of the modules referenced in this description already have JSON examples?

Hm. These examples are very well hidden in the ApiSandbox, not formatted and barely useful when the user wants to build it's own requests. This ticket is about the descriptions.

For wbsetreference the description says "The snaks to set the reference to. JSON object with property IDs pointing to arrays containing the snaks for that property". Something I would love to have is a minimal example like:

{
  "P212": [
    {
      "snaktype": "value",
      "datavalue": { "value": "bar" }
    }
  ]
}

For wbsetclaim the description even says "Statement or Claim serialization". That doesn't even mention JSON. Other API module's descriptions are similar and need improvement.