Extension:Flow/API

From MediaWiki.org
Jump to: navigation, search
See also Flow/Architecture/API and Gerrit change 107411

Most Flow API read and write interactions are submodules of action=flow. Flow also implements a query property flowinfo and a parsing utility module flow-parsoid-utils.

Detection[edit]

prop=flowinfo (details below) is one way to check if Flow is enabled on the specified pages.

You can alternatively use prop=info to retrieve page info including content model. The content model will be 'flow-board' if it's enabled. Compare https://en.wikipedia.org/w/api.php?action=query&titles=Wikipedia%20talk:WikiProject%20Breakfast&prop=info and https://en.wikipedia.org/w/api.php?action=query&titles=Wikipedia%20talk:Articles%20for%20deletion&prop=info .

In client-side JavaScript (for gadgets and user scripts), call mw.config.get( 'wgPageContentModel' ).

prop=flowinfo (fli)

(main | query | flowinfo)
  • This module is deprecated.
  • This module requires read rights.
  • Source: Flow
  • License: GPL-2.0+

Get basic Flow information about a page.

action=flow[edit]

All action=flow requests take the following parameters:

  • submodule: The specific flow submodule you want to use. See below for documentation on some of them
  • workflow: Id of the workflow to take action upon
  • page: Page title of the page to take action upon
  • token: An edit token (see API:Tokens). This is required for all write modules.
  • render: Include this to have an HTML rendering be returned in the output. Used by the extension's JS modules.

For any action that posts data, you will need a token, which defeats cross-site request forgery. To get this, use meta=tokens: Gets a CSRF token

view-topiclist[edit]

submodule=view-topiclist (vtl)

(main | flow | view-topiclist)
  • This module requires read rights.
  • Source: Flow
  • License: GPL-2.0+

View a list of topics.

Parameters:
vtloffset-dir

Direction to order the topics.

One of the following values: fwd, rev
Default: fwd
vtlsortby

Sorting option of the topics, either updated (ordered by topic update time), or newest (ordered by topic creation time).

One of the following values: newest, updated, user
Default: user
vtlsavesortby

Save sortby option to user preferences, if set.

Type: boolean (details)
vtloffset-id

Offset value (in UUID format) to start fetching topics at; used only with newest ordering

vtloffset

Offset value (as a topic update timestamp, in TS_MW format (YYYYMMDDHHMMSS)), to start fetching topics at; used only with updated ordering

vtlinclude-offset

Includes the offset item in the results as well.

Type: boolean (details)
vtllimit

Number of topics to fetch.

No more than 100 (100 for bots) allowed.
Type: integer or max
Default: 10
vtltoconly

Whether to respond with only the information required for the TOC.

Type: boolean (details)
vtlformat

Format to return the content in.

One of the following values: html, wikitext, fixed-html
Default: fixed-html

new-topic[edit]

submodule=new-topic (nt)

(main | flow | new-topic)
  • This module requires read rights.
  • This module requires write rights.
  • This module only accepts POST requests.
  • Source: Flow
  • License: GPL-2.0+

Creates a new Flow topic on the given workflow.

Parameters:
nttopic

Text for new topic title.

This parameter is required.
ntcontent

Content for the topic's initial reply.

This parameter is required.
ntformat

Format of the new topic's initial reply (wikitext|html)

This parameter is required.
One of the following values: html, wikitext
Default: wikitext
token

A "csrf" token retrieved from action=query&meta=tokens

This parameter is required.

(Since this edit operation has to be an HTTP POST, the link in the generated example above won't work.)

action=flow-parsoid-utils[edit]

action=flow-parsoid-utils

(main | flow-parsoid-utils)
  • This module requires read rights.
  • Source: Flow
  • License: GPL-2.0+

Convert text between wikitext and HTML.

Parameters:
from

Format to convert content from.

This parameter is required.
One of the following values: html, wikitext
to

Format to convert content to.

This parameter is required.
One of the following values: html, wikitext
content

Content to be converted.

This parameter is required.
title

Title of the page. Cannot be used together with pageid.

pageid

ID of the page. Cannot be used together with title.

Type: integer