Page MenuHomePhabricator
Create Task
Maniphest T98468

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

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.)

Related Objects
Search...

Event Timeline

thiemowmde created this task.May 7 2015, 1:37 PM
thiemowmde raised the priority of this task from to Needs Triage.
thiemowmde updated the task description. (Show Details)
thiemowmde added projects: Wikidata, MediaWiki-extensions-WikibaseRepository.
thiemowmde added subscribers: thiemowmde, Lydia_Pintscher, JanZerebecki and 2 others.
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.
Lydia_Pintscher moved this task from incoming to ready to go on the Wikidata board.May 15 2015, 2:04 PM
• 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
JanZerebecki added a project: Story.Sep 25 2015, 8:31 PM
Addshore subscribed.Oct 28 2015, 9:19 AM

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

pasted_file (260×1 px, 97 KB)

pasted_file (221×1 px, 101 KB)

thiemowmde added a comment.Oct 30 2015, 9:47 AM

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.

Lydia_Pintscher added a project: patch-welcome.Apr 23 2017, 6:11 PM
thiemowmde added a project: Documentation.Feb 28 2018, 4:32 PM
thiemowmde added a subscriber: Lea_Lacroix_WMDE.
• srodlund moved this task from Backlog to API Documentation Request on the Documentation board.Aug 14 2018, 11:32 PM
Addshore added a parent task: T241215: Improve Wikibase lower and mid level documentation.Dec 20 2019, 9:53 AM
Addshore unsubscribed.Jun 27 2023, 12:42 PM
Content licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) 4.0 unless otherwise noted; code licensed under GNU General Public License (GPL) 2.0 or later and other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct. · Wikimedia Foundation · Privacy Policy · Code of Conduct · Terms of Use · Disclaimer · CC-BY-SA · GPL