I would argue this is not "low" as the API is one of the most important parts of Wikidata.

I set the priority to Low when Sumana left and we had no technical writer to work on this. Now that we have @Spage, things may change. In fact, he is committing to work on T88409 this month, which is blocked by this task. We are planning our ECT monthly sprint today.

In any case, could the Wikidata team assign someone to help S documenting this API and finding good showcases, and documentation in general? I agree with Lydia that this is an area we should prioritize. When I go somewhere public with developers I always get questions about the Wikidata API (last time this weekend at FOSDEM, repeated times).

Cool. @Lucie can hopefully help. Maybe also @Addshore wants to be involved.

*waves* I probably don't have much time to do the writing but will happily read and review it all / point out missing things!

I wonder how these Wikidata API docs will look like, and where will be they published.

In the masterplan, we have agreed that API references should be documented directly in the source code, using the best tool for output. In the case of Wikidata, these APIs are extended MediaWiki APIs. They are referenced in https://www.wikidata.org/w/api.php mixed with all the rest. What is the best way to show them to 3rd party developers willing to learn only about these APIs?

On the other hand, we have https://www.mediawiki.org/wiki/Wikibase/API which I guess is written manually. Will we keep this duplication?

PS: this is the type of problems that the new Developer Hub needs to solve.

I'd be happy to help, too!

In T359#1013892, @Qgil wrote:

I wonder how these Wikidata API docs will look like, and where will be they published.

In the masterplan, we have agreed that API references should be documented directly in the source code, using the best tool for output. In the case of Wikidata, these APIs are extended MediaWiki APIs. They are referenced in https://www.wikidata.org/w/api.php mixed with all the rest.

BTW you can show the generated API documentation for a single action with a parameter, e.g. https://www.wikidata.org/wiki/Special:ApiHelp/wbgetentities

What is the best way to show them to 3rd party developers willing to learn only about these APIs?

I think an on-wiki introduction with motivation and explanation is the way to go. The generated API doc could have a substantial intro explaining items, snaks, etc. but it would have to be repeated for each wikibase API action and we'd need to reproduce wiki markup for sectioning and linking. I'm undecided whether to have examples both in the API, and in the wiki page (T88755: Improve MediaWiki API example behavior).

On the other hand, we have https://www.mediawiki.org/wiki/Wikibase/API which I guess is written manually. Will we keep this duplication?

Per above, yes.
What's confusing me is that page is currently full of generic API documentation and nothing relevant to wikibase! The May 2014 version talks about Wikibase , has helpful advice, and good examples, etc., but then @Christopher (Johnson of WMDE) replaced it with "Please see wikidata.org/w/api.php for a perfectly up to date copy" and then User:D konto (Dionysia Kontotasiou) added a bunch of generic information. I'll revive the May 2014 revision.

PS: this is the type of problems that the new Developer Hub needs to solve.

indeed!

The problem was that the page was out of date and only /api.php was up to date. I did not like that page being filled again as it is confusing now and bound to get out of date again as it is.
So to your question if we keep it if there is something better: hell no :D

In T359#1019615, @Spage wrote:

I'll revive the May 2014 revision.

I did so, generalizing some of the comments, mentioning new modules, and improving the links.

In T359#1020253, @Lydia_Pintscher wrote:

I did not like that page being filled again as it is confusing now and bound to get out of date again as it is.
So to your question if we keep it if there is something better: hell no :D

Yes, developers should definitely improve the generated API help.

It would be nice to get the best of both worlds with T89318: Replace on-wiki API documentation with Special:ApiHelp transclusion. Except... the wikibase API modules don't run on mw.org, nor does Wikibase client, and the transclusion will work across wikis. And there are issues with localization (T89768). Anyway after someone reviews the doc of wbxxx modules on that page for anything missing from the generated API help, we can kill it.

Any on-wiki examples that aren't in the generated API help should use Template:Api ex, e.g. {{Api ex | site=www.wikidata.org | p1=action=wbeditentity | p2=new=item | p3=data={} }}

Is there a good developer-level overview of claims, entities, Q-ids, and snaks somewhere?

Ok let's kill that page then ;-) Do you have time to see if there is anything useful to salvage?

Does this image help you? https://commons.wikimedia.org/wiki/File:Wikidata_statement.svg We have the Wikidata glossary at https://www.wikidata.org/wiki/Wikidata:Glossary but it currently is partially wrong. I will take some time to go through it.

In T359#1046236, @Lydia_Pintscher wrote:

Ok let's kill that page then ;-)

Hold on, I think we need an overview of using the Wikidata API modules and AFAIK I don't think api.php?action=help can generate one. Is https://www.mediawiki.org/wiki/Wikibase/API#General_introduction so terrible :) ?

BTW I see the directory Wikibase/docs/ has various documentation files. Publishing them is T48526: System documentation integrated in source code but it's in nobody's immediate plans. If you envision Wikibase source having an API overview that gets published, I'm supportive.

Do you have time to see if there is anything useful to salvage?

There is stuff worth salvaging, the wiki page has more information than the generated API help, I created subtask T89863: [Task] Merge on-wiki Wikibase/API documentation into Wikibase apihelp strings.. Someone familiar with the code should merge it.

If someone wants to Be Bold in the interim and kill the https://www.mediawiki.org/wiki/Wikibase/API#Modules section that's OK.

Does this image help you? https://commons.wikimedia.org/wiki/File:Wikidata_statement.svg We have the Wikidata glossary at https://www.wikidata.org/wiki/Wikidata:Glossary but it currently is partially wrong. I will take some time to go through it.

Thanks, they're both great! I'll mention them.

https://www.mediawiki.org/wiki/Wikibase/API is in better shape. Community members are also editing it, complicating T89863: [Task] Merge on-wiki Wikibase/API documentation into Wikibase apihelp strings.

In T359#1081097, @Spage wrote:

https://www.mediawiki.org/wiki/Wikibase/API is in better shape. Community members are also editing it, complicating T89863: [Task] Merge on-wiki Wikibase/API documentation into Wikibase apihelp strings.

What about commenting the T89863 plan in the Wikibase/API discussion page, with the intention of getting the editors of that page aware and involve in your efforts?

This task was part of ECT-March-2015, and it is still open and assigned. Assuming that it belongs to ECT-April-2015 as well. Otherwise please edit accordingly.

I'm an Outreachy18 intern and as part of T215682 / T198916 and with help from @srishakatux, I've made the following changes to Wikibase/API in my sandbox (https://www.mediawiki.org/wiki/User:Jeropbrenda/Sandbox/Wikibase/API):

• Reformatted the page to follow API:Tutorial's format.
• Reviewed every part of Wikibase/API to see if there is any information on the page that is missing from apihelp. I found that for all the modules, the parameters listed on-wiki are also in apihelp. In fact, apihelp has more parameters for most of the modules. As for the examples, most of the on-wiki examples are identical to the ones in apihelp, and some only differ by parameter values. One big difference is that some of the on-wiki examples use PHP. That said, and in line with comment #1047482, I have rewritten the on-wiki Modules section to only link each module to it's respective apihelp documentation.

I'd like some feedback as to whether any of the changes I made are inappropriate or if we can merge the changes to the page.

I like the changes. The page is much easier to follow now due to its shorter length, and also we no longer need to try and keep the same docs up to date in 2 places!

@Addshore Thanks for the feedback. I'll integrate the changes to the page in the main namespace.