Flow/Architecture/API

Current API
Flow already has an extensive API, 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 also view it at [//www.mediawiki.org/w/api.php www.mediawiki.org/w/api.php] and play with it at [//www.mediawiki.org/wiki/Special:ApiSandbox#action=flow&format=json Special:ApiSandbox].

It will change from what's implemented as of January 2014.

Sketch
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 action=flow flowaction=reply format=json params={"topic":{ "replyTo":"050fed5dc6bd5085237590b11c2fa805", "content":"My reply, with wikitext."} } render=true token=43a71deb105e7c0be7e8eeab4bdff4f7+\ workflow=050f698e3f6e5624fa1590b11c27932f
 * Request a  API token with.
 * Issue a  API request with , identifying the topic workflow. The parameters for a reply include the topic and the post.
 * Set  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.

If successful, the server responds with the  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.

New API proposal
See
 * addresses issues in

Also query  API to determine if Flow is enabled on a page,, see.

Drop  API.

Other API issues

 * What should happen to regular page API requests made to a Flow-enabled page,


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

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

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