Flow/Architecture/API
This page is obsolete. It is being retained for archival purposes. It may document extensions or features that are obsolete and/or no longer supported. Do not rely on the information here being up-to-date. This page was the original design for the Flow API. The documentation of it actually now works is at Extension:StructuredDiscussions/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.
Most URL (HTTP GET
) and form (HTTP POST
) actions are mirrored in the Flow API.
If you have questions, feel free to ask on #wikimedia-collaboration connect or one of the other places given at Flow#Contact and links.
General comments
editFlow pages are not wikitext pages.
- they use a different ContentModel
- they store revisioned content differently
Consequently, many typical wikitext page API requests, such as newSection
, will not work (bug 57989).
The Flow team has considered mimicking the wikitext APIs, but there's no one right answer to where to modify. For example should a page edit update the board header, or should it create a new topic?
action=query
editprop=info
- returns
"contentmodel": "flow-board"
if it's a Flow board. However, per below, you need to also check that the namespace is not 2600 (NS_TOPIC) currently. Unlike prop=flowinfo, this same API request can also be used for other purposes (e.g. checking protection status).
prop=flowinfo
- returns
enabled
key if Flow is enabled on a page, see Gerrit change 111255. No parameters. As of September 2014 this returns enabled for Flow Topic:UUID pages as well as Flow boards. - You can also check if the content model of a page is
'flow-board'
. As of November 2014 both Flow boards and individual Topic:UUID pages have this content model, bug 71196.)
- obsolete
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.
action=flow API
editThe read and write API consists of submodules of action=flow
, you can see them on the API page www.mediawiki.org/w/api.php.
Read API
editJS in the browser calls the API to
- paginate in the next 10 topics
- request topics in different sort orders
- get the wikitext when editing existing posts
etc.
action=flow
with submodule=
topiclist-view, post-view, topic-view, header-view, topic-summary-view, etc.
Write API
editYou need to decide if your goal is to reply to an existing topic, create a new topic, add something to the Flow board header, or some other interaction.
Sketch of replying
editIn a reply you're replying to a particular post in a workflow (a topic). 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 withflowaction=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.
Block requests
editWhen you make a "Block" API request such as &submodule=new-topic
, the API normally returns a flow.new-topic.result.topiclist
containing updated information about the top 10 topics on the board, including their HTML. This allows the Flow board to redisplay the board contents, but it can be a lot of data.
If you are just trying to add a topic and you're not interested in the board contents, you should pass the flag ntmetadataonly=true
(gerrit:180588)
Flow returns the metadata in a top-level flow.newtopic.committed
key in the API response. For consistency the information about the new content is returned as topic-page, topic-id, topic-revision-id, post-id, header-post-id (but see phab:T84954), etc.
Editing the board header
editIf you want to update the Flow board header, it's similar
- make a GET request
action=flow, submodule=view-header, vhformat=wikitext
to get the current contents. This will return aflow.view-header.result.header.revision
including a UUID of the most recent version of the header inrevisionId
, and its contents incontent.content
. - make a POST request,
action=flow, submodule=edit-header
. Setehprev_revision
to the revision returned by the GET request and setehcontent
to your updated wikitext.
The update may fail with error.code = 'prev_revision'
if someone else updated this board's header between the two requests; if so the return has a prev_revision.revision_id
giving the new latest revision, so you can retry with that. However, you should avoid clobbering the previous editors' work (e.g. by presenting an edit conflict form, or re-running the algorithm if a bot is making the requests, etc.).
flow-parsoid-utils
editRequests 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 its own API.
Future API changes
editEventually move to a service-oriented architecture. Might look like proposed Content API.
External clients should be able to use OAuth to authorize bots to make Flow changes on their behalf. This should work for the most common actions, such as posting a new topic and replying. Anything requiring the Flow rights (e.g. flow-hide, flow-lock, flow-delete, flow-edit-post) will likely be forbidden via OAuth until it's properly exposed, bug 72998.
Should existing API calls that interact with a page "just work" on a Flow board?
editWhat should happen to regular page API requests made to a Flow-enabled page is phab:62808. Probably not in general, since the caller really has to decide whether the change is to the board header or a new topic
But perhaps some variations where intent is obvious:
- Specifically
action=edit§ion=new
on a talk page means create a new topic, so why not have that work on a Flow board (phab:T59989, status As of March 2014 is "Declined") - Likewise
action=edit&appendtext=wiki+text+to+add
andprependtext=...
could append and prepend to a Flow board header (phab:T85197)- These may not work as well. For
appendtext
especially, there is no way to tell whether they are intending to add to the header, add a new topic, or add content to the end of the last topic.
- These may not work as well. For
Other API issues
edit- post editing rights for bots.
- ordinarily only the poster can edit their reply, unlike a regular wiki page.
Missing APIs?
editAPI to enumerate pages / namespaces that are using Flow?
editCurrently, would just return values of $wgFlowOccupyPages
and $wgFlowOccupyNamespaces
. Now that a Flow board has a special content type, the former could be replaced by a query for pages with the flow-board
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?
editincludes/UrlGenerator.php can fabricate all kinds of URLs. May API queries return these URLs in the links
object for each topic and post, but clients can't create their own. Given a topic UUID you can simply make a title object for Topic:UUID
but fabricating a link to a post or a link to view a topic in context on a board requires knowledge of Flow internals.
- PossibleoOptions: wiki link or URL; show standalone topic or show Flow board paginated to topic
Use cases
edit- please update, especially with links to bots (Flow/Bots)
Posting a new topic from on-wiki JavaScript
editIf an on-wiki user script or gadget needs to be post a new topic, the best way is to use MessagePoster. The advantage is that you don't need to know whether the talk pages uses old-style talk pages or Flow. It will work either way (LiquidThreads is not supported).
mw.loader.using( [ 'mediawiki.Title', 'mediawiki.messagePoster' ], function () {
var title = new mw.Title( 'Talk:MyTalkPage' );
var posterPromise = mw.messagePoster.factory.create( title );
posterPromise.done( function ( poster ) {
poster.post( 'This is the topic title', 'This is the body of a message posted with MessagePoster' );
} );
} );
Detects whether it is interacting with a Flow board by checking $title->hasContentModel( 'flow-board' )
; if so then adds its message to the Flow board by making an API request with action=flow
submodule=new-topic
(see patch).
This creates a Flow board pairing a new editor with a mentor.
It makes a new-topic
API request to add a welcome message to a non-existent page, and because it's in the "flow-bot" group which has the flow-create-board
right this succeeds and creates a Flow board.
Bots patrolling new content
edit- ? have to watch for changes
- ask for new and changed topics and posts
Bots making edits
editThere is in-progress support in pywikibot, in the pywikibot-flow project. Some key functionality, including creating new topics, replying, and resolving/reopening topics, is already implemented. Bot owners need to add the code examples listed at Manual:Pywikibot/Flow.
- 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 <!-- comment -->.
- 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
edit- 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.
Finding links
editIn bug 57512 comment#22 Brad Jorsch commented:
- And there are also a number of API modules that query the existing links tables; there should at least be some way to (1) identify that a page is Flow and (2) search these flow-specific links tables to find the actual "thing(s)" doing the linking in the particular page.
Flow/Architecture#Link handling sketches the implementation.
?
editNon-issues
editNo need to check for unsigned edits, replies are known.
See also
edit- bug 57659 main API improvement bug
- announcement at w:WP:Bot owners' noticeboard#New extension: Flow