API:数据格式

This page is a translated version of the page API:Data formats and the translation is 62% complete.

输入

API是通过询问字符串以提供该参数,或者是以application/x-www-form-urlencodedmultipart/form-data形式进行的HTTP请求。 每个模块和子模块都有自己的一组参数,这些参数在文档和action=help中列出。也可以通过action=paraminfo 检索它们。

编码

所有输入在UTF-8,以及NFC的表格里应当是有效的。 MediaWiki将会尝试转换为其他的格式,这或许会导致程序上的错误。

多值参数

Parameters that take multiple values are normally submitted with the values separated using the pipe character (|), e.g. param=value1|value2. If a value contains the pipe character in itself, use U+001F (Unit Separator) as the separator and prefix the value with U+001F, e.g. param=%1Fvalue1%1Fvalue2.

Whether a parameter accepts multiple values is listed explicitly in its module documentation.

布尔参数

If a boolean parameter is specified in an HTTP request, it is considered true regardless of its value. For a false value, omit the parameter entirely. The best way to specify a true parameter in an HTTP request is to use someParam=; the trailing = ensures the browser or HTTP library does not discard the "empty" someParam.

时间戳

Parameters that take timestamp values accept multiple timestamp formats:

时间戳总是输出ISO 8601格式。

输出

The standard and default output format in MediaWiki is JSON. All other formats are discouraged.

The output format should always be specified using format=yourformat with yourformat being one of the following:

  • json: JSON格式。(推荐)
  • php: 序列化PHP格式 (已弃用)
  • xml: XML格式 (已弃用)
  • txt: PHP print_r()格式 (在1.27版本中已移除)
  • dbg: PHP var_export()格式 (在1.27版本中已移除)
  • yaml: YAML格式 (在1.27版本中已移除)
  • wddx: WDDX格式 (在1.26版本中已移除)
  • dump: PHP var_dump()格式 (在1.26版本中已移除)
  • none: 返回空白响应 1.21+

例子

获取JSON中的输出。


回应

{
  "query": {
    "pages": {
      "217225": {
        "pageid": 217225,
        "ns": 0,
        "title": "Main page"
      }
    }
  }
}

Unless specified, all modules allow data output in all generic formats. To simplify debugging, all generic formats have "pretty-print in HTML" alternatives with an fm suffix, e.g. jsonfm.

JSON参数

The following parameters can be used with format=json and format=jsonfm:

  • utf8: 把大多数(并非全部)非ASCLL字符编码为UTF-8,而不是用十六进制的转义序列替换它们。 类型: boolean.
  • ascii: 把所有的非ASCLL字符编码十六进制的转义序列。 类型: boolean.
  • formatversion: 输出格式。 1.25+
    • 1: Backwards-compatible format, uses * keys for content nodes, encodes non-ASCII characters using hexadecimal escape sequences.
    • 2: Modern format. Returns responses in a cleaner format, encodes most non-ASCII characters as UTF-8. (recommended)
  • callback: The function in which the result will be wrapped. For safety, all user-specific data will be restricted. A number of things are disabled for security:
    • The client is treated as an anonymous user (i.e. not logged in) for all purposes, even after logging in through action=login .

This means that modules which require additional rights won't work unless anonymous users are allowed to use them.

补充资料

  • XML和PHP输出格式已废弃但仍被使用。 Clients written in PHP should avoid using the PHP format because it is fundamentally insecure. It is maintained for now only due to its popularity.
  • There are many conversion libraries and online converters to convert JSON responses to other formats—for example, JSON-CSV converts to Comma-Separated Values.
  • Feed modules like Feed Recent Changes override the standard output format, instead using RSS or Atom, as specified by their feedformat parameter.

在那些情况中,被format参数指定的格式只会在发生错误时使用。

参见