Page MenuHomePhabricator

Working with the fancy old MediaWiki API
Closed, ResolvedPublic

Description

Session title

Working with the fancy old MediaWiki API

Main topic

Building on Wikimedia services: APIs and Developer Resources

Type of activity

Unconference session

Description



=== 1. The problem ===
Discussion about the action API tends not to happen very much, but when given the chance people do seem to like to ask @anomie questions. So let's give them the chance if they want it.

=== 2. Expected outcome ===
Improved understanding of how the action API is designed and where we may want to go in the future.

=== 3. Current status of the discussion ===
Not much discussion since last year's session, {T122818}. Brad has been asked for some additional reviews, which is good. I don't know whether anyone has taken on improving the documentation on mediawiki.org.

=== 4. Links ===
* Last year's action API-related topic: {T122818}

== Proposed by ==
@Anomie

== Preferred group size ==
However many people want to talk. Last year we had 12, I'd guess we'll have about the same this year.

== Any supplies that you would need to run the session ==
Nothing comes to mind.

== Interested attendees (sign up below) ==

# @Tgr
# @jcrespo
# @MusikAnimal
# @Siznax
# @Niedzielski
# @Mholloway
# Add your name here

Event Timeline

Anomie created this task.Oct 21 2016, 5:17 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptOct 21 2016, 5:17 PM

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

General notes from T122818

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?
Tgr added a subscriber: Tgr.Oct 31 2016, 2:57 AM
Tgr added a comment.Oct 31 2016, 4:16 AM

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

Qgil added a subscriber: Qgil.Nov 10 2016, 11:33 AM

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.

Anomie updated the task description. (Show Details)Nov 10 2016, 3:13 PM
Qgil added a comment.Nov 15 2016, 12:26 PM

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.

Siznax added a subscriber: Siznax.

Should this be moved to the Unconference column then?

Seb35 awarded a token.Nov 28 2016, 7:43 AM
Seb35 added a subscriber: Seb35.

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

Anomie updated the task description. (Show Details)Dec 16 2016, 7:03 PM
Tgr awarded a token.Dec 23 2016, 2:10 AM
Tgr updated the task description. (Show Details)
Tgr added a comment.Dec 23 2016, 2:40 AM

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.

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, {{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.

jcrespo updated the task description. (Show Details)Dec 23 2016, 8:40 AM
Tgr added a comment.Dec 23 2016, 11:42 AM

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

bd808 added a subscriber: Gilles.Dec 23 2016, 3:02 PM

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.

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.

MusikAnimal updated the task description. (Show Details)Dec 23 2016, 7:17 PM
Siznax updated the task description. (Show Details)Jan 2 2017, 8:11 PM
Niedzielski updated the task description. (Show Details)Jan 3 2017, 4:42 PM
Niedzielski added a subscriber: Niedzielski.
Mholloway updated the task description. (Show Details)Jan 4 2017, 6:46 PM
Mholloway added a subscriber: Mholloway.

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! :)

Tgr added a comment.Jan 9 2017, 8:38 AM
This comment was removed by Tgr.
Anomie added a comment.Jan 9 2017, 5:11 PM

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.

Tgr added a comment.Jan 9 2017, 6:26 PM
This comment was removed by Tgr.
Tgr added a comment.Jan 9 2017, 7:24 PM

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!

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?

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? :)

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.

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

Anomie closed this task as Resolved.

Since the notes are posted and the action items are taken care of, I suppose this should be marked resolved.