Flow/Architecture/API

Current API

Flow has an extensive API that's heavily exercised by one client – the JavaScript on Flow boards – as you can see if you interact with a Flow board with JavaScript enabled and watch the API requests in your browser's developer tools > Network tab.

You can drive the API from Special:ApiSandbox.

Write API

The write API consists of submodules of action=flow, you can see them on the API page www.mediawiki.org/w/api.php.

Read API

JS in the browser calls the API to

paginate in the next 10 topics
get the wikitext for

Currently

action=flow with either

list=flow: any flowaction is passed on to WorkflowLoader, which will create multiple block objects and pass the flowaction onto them. flowaction can be view, header-view, and topic-summary-view. Each of these they take different parameters.

prop=flowinfo: returns enabled if Flow is enabled on a page, see Gerrit change 111255. No parameters

Coming soon read API

Patches in gerrit change the read API to be more like the write API, so there will be specific actions for flow.

There will be different submodules for view, topic summary, and header, maybe post view.

flow-parsoid-utils

Requests conversion between html and wikitext. If the wiki isn't running Parsoid, conversions from html to wikitext will fail.

This is meant to be an "internal" API for Flow to be able to communicate with Parsoid client-side. If you want to convert wikitext<-->html using Parsoid, you should use it's own API.

Sketch of write API

In a reply you're replying to a particular post in a workflow (a topic). See Flow/Nomenclature for an explanation of the terms. Flow objects are identified by UUIDs see Flow/Architecture.

To reply to a topic

you'll need a token. Flow recently switched to using the regular 'edit' token for most operations, so you can use mw.api.postWithEditToken to get the editing token if it hasn't been cached yet in the session. it's cached.
Issue a flow API request with flowaction=reply, identifying the topic workflow. The parameters for a reply include the topic and the post.

action=flow
submodule=reply
format=json
repreplyTo=050fed5dc6bd5085237590b11c2fa805
repcontent=My reply, with ''wikitext''.

render=true
token=43a71deb105e7c0be7e8eeab4bdff4f7+\
workflow=050f698e3f6e5624fa1590b11c27932f

Set render=true if you want the server to respond with the "fully-decorated" HTML to interact with the new post (preview buttons, actions, etc.).
UUID format will soon change to be more compact, using 88-bit represented as alphadecimal.
Obviously you get the topic and post to respond by making API queries, rather than hardcoding these numbers.

Note that a wiki may store Flow content with $wgFlowContentFormat 'html' or 'wikitext', but in any edit submission you must (?) submit wikitext.

If successful, the server responds with the post-id of the new post, and the HTML to insert into the DOM.

Note this API request doesn't name the page on which the topic appears. Users interact with topics on a Flow board with a wiki page name, but a topic might (eventually) appear on multiple pages, e.g. a user's "subscription feed".

On WMF wikis, Flow stores post content as HTML with embedded Parsoid markup so that the original wikitext can be reconstituted for editing. This will not be the case on all wikis, others might store as wikitext.

Future API changes

Eventually move to a service-oriented architecture. Might look like proposed Content API.

Other API issues

Should existing API calls to edit to a page "just work" on a Flow-enabled "page"?
What should happen to regular page API requests made to a Flow-enabled page, bug 60808.
- This will change somewhat when a Flow board becomes a content type.

post editing rights for bots.
- ordinarily only the poster can edit his or her reply, unlike a regular wiki page.

Missing APIs?

Do people need an API to enumerate pages / namespaces that are using Flow?
- currently, would just return values of $wgFlowOccupyPages and $wgFlowOccupyNamespaces. When a Flow board becomes a content type, the former could be replaced by a query for pages with the flowboard contentmodel, though there does not seem to be a generator for this.

API to generate a link to a post/topic/board given a UUID
- Options: wiki link or URL; show standalone topic or show Flow board paginated to topic
- must caller be aware of whether the UUID is a workflow (topic) or post or header?
- note redirector functionality (e.g. Special:Flow/workflow/ru0aehx63b43khdl and Special:Flow/post/ru22c9f18csotjs7) is in release 1.24wmf4.

Use cases

please update, especially with links to bots

Bots patrolling new content

? have to watch for changes
ask for new and changed topics and posts

Bots making edits

Adding topics (and/or posts)
Correcting old posts
Modifying talkpage headers
Checking if the bot has already made a particular post to a particular page
- Often implemented by a subject line check, or a check for a particular .
- Ability for users to remove or otherwise signal that the bot-raised issue is taken care of, so the bot can know to repost it if it recurs.
Opting out of bot messages (eg. Enwiki's template:nobots).

Tools showing count of edits

Contributions with Flow at some wiki aren't included in X!'s Edit Counter for that wiki, maybe because Flow is in a separate database. See bug 61887, though this is more a DB tool than a bot.

?

Non-issues

No need to check for unsigned edits, replies are known.