This session should be a followup to last year's T122818

General notes from T122818

• Is there a long-term plan for the action API? (Currently work is done ad-hoc)
• RFC/API roadmap
• API/Architecture_work/Planning
• @bd808's notion of code pioneer/settler/city planner for code (http://blog.gardeviance.org/2015/03/on-pioneers-settlers-town-planners-and.html among others)
• Is the purpose to avoid dealing with wikitext? No, not really--you can get HTML out of it, but also handle wikitext.
• API in layers--wikitext, template, other information to allow user parsing?
• Quarry (web interface for db queries) records queries, can be a useful learning too for newcomers. replicate the same for api sandbox?
• on the same theme, see also Jupyter-Hub on https://wmflabs.org to control pywikibot

Action items with owners:

• Fhocutt: suggest API use-case categorization for hackathon
• !Brad: ask Brad/anomie to review code for API modules, and set aside time to deal with resulting comments. Add anomie as a reviewer on an API-related patch, and if he's not looking at it ping him via email/IRC.
• vague, no one is assigned to it: fix up API documentation. Make a list of pages that need fixing?

I was thinking about proposing a session about API metrics (optimistically assuming we will have API metrics by then), but maybe it could be folded into this? (It would make sense to have a separate session with nontechnical focus as metrics / questions about who our userbase is are more interesting for product/partnership people; but then again, historically product/partnership people have not shown up much at WikiDev.)

Please remember the next deadline in the selection process:

2016-11-14: Deadline for defining a good problem statement, expectations, and links to relevant resources.

That is next Monday.

I'd still like to have a session along the lines of last year's T122818: MediaWiki Action API design discussion: the amazing/good/bad/ugly if people are interested in attending. Unfortunately, with the sudden and mysterious disappearance of Robla I'm not sure what to actually write for the fields here beyond the little bit I've already written.

In T148855#2785820, @Anomie wrote:

I'd still like to have a session along the lines of last year's T122818: MediaWiki Action API design discussion: the amazing/good/bad/ugly

According to the notes, there were 12 participants. This would be a good size for an Unconference session. Does this work for you?

That seems ok.

Should this be moved to the Unconference column then?

@Anomie Hey! As developer summit is less than four weeks from now, we are working on a plan to incorporate the ‘unconference sessions’ that have been proposed so far and would be generated on the spot. Thus, could you confirm if you plan to facilitate this session at the summit? Also, if your answer is 'YES,' I would like to encourage you to update/ arrange the task description fields to appear in the following format:

Session title
Main topic
Type of activity
Description Move ‘The Problem,' ‘Expected Outcome,' ‘Current status of the discussion’ and ‘Links’ to this section
Proposed by Your name linked to your MediaWiki URL, or profile elsewhere on the internet
Preferred group size
Any supplies that you would need to run the session e.g. post-its
Interested attendees (sign up below)

1. Add your name here

We will be reaching out to the summit participants next week asking them to express their interest in unconference sessions by signing up.

To maintain the consistency, please consider referring to the template of the following task description: https://phabricator.wikimedia.org/T149564.

IMO currently the biggest problem with API is documentation. It suffers from the mw.org / code documentation split even more than the rest of MediaWiki; mw.org documentation is a mix of high-value manual documentation and low-value autogenerated API help text (which is a maintainence burden and probably better replaced with links) and extension-provided API modules are undiscoverable (if documented at all). Most links point to Special:ApiHelp instead of the much more powerful sandbox. There is no clear separation of what can be done with MediaWiki, what can be done with core and what can be done on Wikipedia.

The sandbox is very powerful and a great improvement over the previous status quo but not beginner-friendly. There is no search functionality, no feedback (it would be nice if people could tell when the documentation sucks, which is the case of lots of API modules) or "ask a question" functionality, it does not promote best-practice default settings (e.g. defaults to formatversion=1), it does not offer code snippets (make this call in curl, make this call in mw.Api etc). Links in help text lead to the much-inferior ApiHelp. The sandbox and on-wiki documentation are not cross-linked (and generally the sandbox is not promoted nearly as much as it should on-wiki). The sandbox is not promoted in format=*fm API results.

In T148855#2897924, @Tgr wrote:

IMO currently the biggest problem with API is documentation.

This was discussed during last year's session, but no one took on the action item.

* vague, no one is assigned to it: fix up API documentation. Make a list of pages that need fixing?

It's a wiki, anyone can edit it, but not too many people seem to want to do so. Unless you have ideas on how to change that, just reiterating that the wiki needs updating doesn't help much.

The auto-generated help could probably also use some work. Editing i18n messages is harder than editing a wiki, but not by much. Again, though, not many people seem to be interested.

It suffers from the mw.org / code documentation split even more than the rest of MediaWiki; mw.org documentation is a mix of high-value manual documentation and low-value autogenerated API help text (which is a maintainence burden and probably better replaced with links)

Note that Special:ApiHelp can be transcluded, although some pages still have a copy-paste of the auto-generated documentation from before Special:ApiHelp existed. See also T89318: Replace on-wiki API documentation with Special:ApiHelp transclusion and T89768: Language support in Special:ApiHelp and its transclusion..

and extension-provided API modules are undiscoverable (if documented at all).

They don't need to be. They're as discoverable as anything else in the auto-generated documentation, and they can be documented on the wiki in whatever way people like (it's a wiki!).

Most links point to Special:ApiHelp instead of the much more powerful sandbox.

Which links are you talking about? The links on the wiki, except for those transcluded from Special:ApiHelp, probably link to other wiki pages rather than Special:ApiHelp. The links in the auto-generated documentation link to the auto-generated documentation because it's supposed to be linking to documentation, not to a sandbox.

There is no clear separation of what can be done with MediaWiki, what can be done with core and what can be done on Wikipedia.

This comment makes no sense.

There is no search functionality [in the sandbox],

Note the sandbox is a sandbox, not documentation. It does include documentation, but its primary purpose is to be a sandbox.

no feedback (it would be nice if people could tell when the documentation sucks, which is the case of lots of API modules)

Phabricator exists. I don't think trying to build some sort of ArticleFeedback-like feature in ApiSandbox is worth the trouble. I suppose we could include a button that links to https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?tag=MediaWiki-API to make it slightly easier to report bugs. Or even better, a custom form with a useful prefill.

or "ask a question" functionality,

The sandbox is also not IRC, email, or talk pages. It's a sandbox. I wouldn't be opposed to adding a button somewhere in the interface that links to a local-wiki-configurable page, but not beyond that.

it does not promote best-practice default settings (e.g. defaults to formatversion=1),

The sandbox generally doesn't override API defaults. The exceptions are for usability:

• It removes the default for the action parameter because using the sandbox to hit action=help would be silly and doesn't give useful output (try it).
• It changes the default for format to json because the sandbox doesn't support the real default jsonfm.

I suppose there's not any particular reason not to allow for overriding things like formatversion, though, besides that we might wind up with bikeshedding over which things need overriding.

it does not offer code snippets (make this call in curl, make this call in mw.Api etc).

The sandbox is also not StackOverflow. See also T130501: Show query parameters on Special:ApiSandbox as a JSON object, as well as a query string where this topic has received more discussion. At the moment it seems bogged down in the obvious question of how to decide which formats to include.

Links in help text lead to the much-inferior ApiHelp.

As opposed to what? If you want to link to the wiki pages, that's a matter of editing the i18n messages but I suspect it's probably more useful for the auto-generated help to link to the auto-generated help than to on-wiki documentation that isn't kept up to date very well. If you want to link to the sandbox, I'll say again that the sandbox isn't documentation.

The sandbox and on-wiki documentation are not cross-linked (and generally the sandbox is not promoted nearly as much as it should on-wiki).

If the on-wiki documentation uses the {{ApiEx}} template, it includes a "try in ApiSandbox" link. The sandbox links to the on-wiki documentation wherever the module provides such links by overriding ApiBase::getHelpUrls(), click the "Help Links" button.

If you want to promote the sandbox more on-wiki, [[https://en.wikipedia.org/wiki/Template:Sofixit|{{sofixit}}]]. Again, the problem here isn't in deciding to do it, it's in finding anyone who wants to actually do the work.

The sandbox is not promoted in format=*fm API results.

In abstract this wouldn't be particularly difficult for someone to implement. Certainly it would be easier than T123905: MediaWiki api.php's HTML representation of the JSON format should link "format=json" since you don't have to worry about the POST issue. In practice you might run into trouble for certain requests if browsers limit the length of (the fragment portion of) links, so it might be a good idea to omit the link if it would be excessively long.

There is no reason for the sandbox to not be documentation. It's not an unusual choice - API documentation generators like Swagger tend to do that. Most of the on-wiki documentation could be removed after that, and the rest would be easier to keep up to date. To me, the API sandbox feels more user-friendly then the wiki or ApiHelp even when used purely as a documentation tool (I have completely stopped using the other two once I got used to it) - I guess part of that is that it's more responsive due to the single-page app design. It contains slightly less information (e.g. omits the type) but that could be fixed easily. Also, eventually the help should have interactive navigation (e.g. search in API module descriptions - finding the right module by browsing some huge list is inconvenient) and it seems a lot easier to add that to the sandbox than to ApiHelp or the wiki (well, the wiki does have search, but it's not great).

I think there are two fundamental use cases for looking at API docs: either you have a wiki and a task and want to figure out how the API can help with it, or you have a task and you are the wiki operator and want to figure out how the wiki could provide an API (what extensions to install). For the first on-wiki documentation is not really useful (it won't have the right API modules; it might document a newer version; some API functionality might depend on configuration settings). For the second it could be if it would be focused on that.

Note that Special:ApiHelp can be transcluded

If it's a core module or the extension is installed on mediawiki.org.

Which links are you talking about?

Links in documentation messages which point to ApiHelp should be automatically rewritten IMO. For example if you try to use the old login API in the sandbox, there will be a token field with a link to the meta=tokens action, but the link takes you to ApiHelp so actually getting that token is more work than it should be.

I don't think trying to build some sort of ArticleFeedback-like feature in ApiSandbox is worth the trouble.

Definitely not. But buttons linking to Phabricator, the support desk, Stackoverflow would be nice.

I suppose there's not any particular reason not to allow for overriding things like formatversion, though, besides that we might wind up with bikeshedding over which things need overriding.

The things which take some default value for B/C reasons but you wouldn't suggest people writing new code to use them. formatversion=1, errorformat=bc, old-style continuation in the past...

The API documentation sub-topic seems closely related to T149372: MediaWiki Documentation and to the identified problem in Labs/Tool Labs of missing tutorials. The meta question, and it is not a new question, is how to attract people who are interested in technical writing to contribute.

We have a large community of people who are interested in encyclopedic writing, but very few who seem to be interested in technical writing. I have a theory that people who excel at encyclopedic writing are uncomfortable doing technical writing because the two styles of writing are so wildly different. Generally in technical writing you are attempting to create a primary source of information rather than citing one. I know I have heard from people in Labs/Tool Labs that they feel that they do not have "enough" knowledge to contribute to the existing documentation. I wonder how we can work to break down that mental barrier and encourage people to try to explain the things that they have learned through trial and error, asking questions, and reading code.

Another random idea, use @Gilles old idea about soliciting contributions from employees of other tech companies specifically to recruit people with professional technical writing experience. Getting just a few pieces of documentation to "featured article" quality might go a long way towards helping with the larger problem by giving a standard for others to aspire to.

In T148855#2898581, @Tgr wrote:

There is no reason for the sandbox to not be documentation.

Except that it does a somewhat crappy job of it since it's designed as a sandbox, not as documentation. I wouldn't want to try grafting a search UI into it, for example.

API documentation generators like Swagger tend to do that.

From what I've seen of Swagger, it's designed for REST APIs with multiple endpoints that each take only a handful of parameters, and generates a "sandbox" for each individual endpoint. Even there you can't easily search all the endpoints. And then consider that a sandbox for even the simplest action API request needs to include three "endpoints" (main, action, format) rather than just one, even if most of the time you can ignore two of them.

Most of the on-wiki documentation could be removed after that,

Only because much of the existing on-wiki documentation is still outdated copy-pastes from the auto-generated documentation.

It contains slightly less information (e.g. omits the type) but that could be fixed easily.

The sandbox doesn't need to state the type, because the fields already control the typing.

Also, eventually the help should have interactive navigation (e.g. search in API module descriptions - finding the right module by browsing some huge list is inconvenient)

The huge list has the advantage that you can use your browser's search tools. It's also more likely that a generic search engine could index the HTML documents rather than something embedded in a JS web application.

I think there are two fundamental use cases for looking at API docs: either you have a wiki and a task and want to figure out how the API can help with it, or you have a task and you are the wiki operator and want to figure out how the wiki could provide an API (what extensions to install).

My fundamental use case is different from both of those: I already know what I want to do with the API, but I need a reminder of what the parameter is named or what the specific value is.

Note that Special:ApiHelp can be transcluded

If it's a core module or the extension is installed on mediawiki.org.

True.

Which links are you talking about?

Links in documentation messages which point to ApiHelp should be automatically rewritten IMO. For example if you try to use the old login API in the sandbox, there will be a token field with a link to the meta=tokens action, but the link takes you to ApiHelp so actually getting that token is more work than it should be.

That's a bad example to use. Most token fields in the sandbox have a widget to automatically fetch the token, but action=login doesn't because it doesn't use the standard 'token' type for hysterical raisins.

There's something to be said for linking directly to the needed query in addition to linking to documentation about the needed query. The UI of including that in running text would need some thought.

I don't think trying to build some sort of ArticleFeedback-like feature in ApiSandbox is worth the trouble.

Definitely not. But buttons linking to Phabricator, the support desk, Stackoverflow would be nice.

Linking to StackOverflow sets off my "torches and pitchforks" detector, as in if we make that part of MediaWiki core we'll have people coming after us with such implements. If we want to allow wiki admins to add such buttons, it'd need to be a more general "add buttons that link to stuff" configuration option of some sort.

To the facilitator of this session: We have updated the unconference page with more instructions and faqs. Please review it in detail before the summit: https://www.mediawiki.org/wiki/Wikimedia_Developer_Summit/2017/Unconference. If there are any questions or confusions, please ask! If your session gets a spot on the schedule, we would like you to read the session guidelines in detail: https://www.mediawiki.org/wiki/Wikimedia_Developer_Summit/2017/Session_Guidelines. We would also then expect you to recruit Note-taker(s) 2(min) and 3 (max), Remote Moderator, and Advocate (optional) on the spot before the beginning of your session. Instructions about each role player's task are outlined in the guidelines. The physical version of the role cards will be available in all the session rooms! See you at the summit! :)

Sigh, the most common agent after Parsoid is the empty agent.

Also, it might be helpful to generate the same stats with internal requests (e.g. Parsoid) filtered out.

Deleted the comments with UAs for now, pending T154912.

Note-taker(s) of this session: Follow the instructions here: https://www.mediawiki.org/wiki/Wikimedia_Developer_Summit/2017/Session_Guidelines#NOTE-TAKER.28S.29 After the session, DO NOT FORGET to copy the relevant notes and summary into a new wiki page following the template here: https://www.mediawiki.org/wiki/Wikimedia_Developer_Summit/2017/Your_Session and also link this from the All Session Notes page: https://www.mediawiki.org/wiki/Wikimedia_Developer_Summit/2017/All_Session_Notes. The EtherPad links are also now linked from the Schedule page (https://www.mediawiki.org/wiki/Wikimedia_Developer_Summit/2017/Schedule) for you!

The etherpad for this session was https://etherpad.wikimedia.org/p/devsummit17-ActionAPI

Change 331419 had a related patch set uploaded (by Anomie):
API: Add reference to the mailing list in errors and deprecation warnings

https://gerrit.wikimedia.org/r/331419

Change 331420 had a related patch set uploaded (by Anomie):
Add reference to Special:ApiFeatureUsage to the 'deprecation-help' warning

https://gerrit.wikimedia.org/r/331420

Sorry I wasn't able to attend this session. Quickly glancing at the notes, I saw:

Q: Is the plan to move away from the action API?
A: Yes, but we try to maintain backwards compability and functionality

Was this something that participants at the session today agreed to?

If someone put that in the notes, they must have mistyped or misunderstood.

That would appear to be @jmadler?

In T148855#2929793, @Anomie wrote:

If someone put that in the notes, they must have mistyped or misunderstood.

Do you think you could update the notes with what was discussed then? :)

In T148855#2929834, @Legoktm wrote:

In T148855#2929793, @Anomie wrote:

If someone put that in the notes, they must have mistyped or misunderstood.

Do you think you could update the notes with what was discussed then? :)

I made a few edits.

Thanks. I've moved the notes to https://www.mediawiki.org/wiki/Wikimedia_Developer_Summit/2017/Action_API

Change 331419 merged by jenkins-bot:
API: Add reference to the mailing list in errors and deprecation warnings

https://gerrit.wikimedia.org/r/331419

Change 331420 merged by jenkins-bot:
Add reference to Special:ApiFeatureUsage to the 'deprecation-help' warning

https://gerrit.wikimedia.org/r/331420