您的位置: 首页  >  文章  >  xwiki功能-XWikiRESTfulAPI

xwiki功能-XWikiRESTfulAPI

分类: 文章 • 2025-06-12 11:54:45
内容

XWiki通过一个基于HTTP语义的API来访问几乎每一个元素，即RESTful API。在本页中，你会发现这个API的所有细节，并利用这个API充分发挥它的优势。

访问该服务

默认情况下，XWiki RESTful API的根入口是以下URL：


  http://host:port/xwiki/rest
 

所有资源在XWiki RESTful API 文档描述。 

例如：在localhost端口为8080下/wikis资源可以用以下URL检索： http://localhost:8080/xwiki/rest/wikis

除了可以检索XML格式的内容，你也可以通过添加参数?media=json来检索JSON格式的内容。例如：http://localhost:8080/xwiki/rest/wikis?media=json

数据集

本节包含了对XWiki数据集简短描述来展示resources及其相关操作。

XWiki在空间组织页面。每一页面都有多个版本（历史记录）和翻译。翻译的页面都有独立的自己的版本和历史记录。每个页面可能有附件。每个附件都有自己的历史记录。附件被一个页面的所有不同的翻译间共享（即不管页面语言是什么，附件是用同一组附件）。 页面可以有一个或多个对象。对象是包含一组属性的类的实例。有些对象可能会被直接公开为类的实体，如注释和tags。对象和附件一样，被页面不同翻译间共享。

了解resources和representations

"REST中一个重要的概念是resources（具体信息来源），每种资源对应一个全局标识符（例如，HTTP中URI）。为了操作这些资源，网络组件（用户代理程序和源服务器，即浏览器和服务器）通过标准接口（例如，HTTP）进行通信以及交换资源的representation（表现形式）。" 

在XWiki，资源是页面，附件，对象，属性，空间，以及我们在上一节中所描述的东西。 XWiki有一个默认的方式传达这些资源信息，即提供定义XML representation，包含以XML格式关联资源的所有信息。此格式描述使用的是XML Schema定义文件。

当然相同的资源可以用不同的方式来表示。

representation另一个重要的方面是资源表达中包含了链接信息。这是超媒体即应用状态引擎(HATEOAS，客户端通过服务器提供的超媒体内容中动态提供的动作来进行状态转换)原则。在XML表示该信息是通过<link>标签来传达。这种标签有两个重要的参数：rel和href。 rel指定链接的“语义”，而href是链接资源的URI。

例如，一个页面的representation，我们可以有评论，tag，附件(关联到当前页面的独立资源)的链接。这些链接是由页面的XML representation提供并且允许客户浏览到相关的资源...就像我们每天点击的web页面链接一样。
xwiki功能-XWikiRESTfulAPI

关系

你可能会在XML资源表现形式找到如下可用关系：

Rel 语义
http://www.xwiki.org/rel/wikis 包含虚拟wiki列表的表现形式。
http://www.xwiki.org/rel/spaces 含在一个wiki下空间列表的表现形式。
http://www.xwiki.org/rel/pages 含在一个空间下页面列表的表现形式。
http://www.xwiki.org/rel/translation 一个页面翻译的表现形式。
http://www.xwiki.org/rel/page 一个页面的表现形式。
http://www.xwiki.org/rel/space 一个空间的表现形式。
http://www.xwiki.org/rel/parent 当前资源的父页面的表示形式。
http://www.xwiki.org/rel/home 当前资源的home页面的表示形式。
http://www.xwiki.org/rel/attachmentData 实际附件数据的表示形式。
http://www.xwiki.org/rel/comments 当前资源关联注释列表的表示形式。
http://www.xwiki.org/rel/attachments 当前资源关联附件列表的表示形式。
http://www.xwiki.org/rel/objects 当前资源关联对象列表的表示形式。
http://www.xwiki.org/rel/object 一个对象的表现形式。
http://www.xwiki.org/rel/classes 当前资源关联类列表的表示形式。
http://www.xwiki.org/rel/history 当前资源关联历史信息列表的表示形式。
http://www.xwiki.org/rel/class 一个类的表现形式。
http://www.xwiki.org/rel/property 一个属性的表现形式。
http://www.xwiki.org/rel/properties 当前资源关联属性列表的表示形式。
http://www.xwiki.org/rel/modifications 当前资源关联修改列表的表示形式。
http://www.xwiki.org/rel/children 当前资源关联孩子列表的表示形式。
http://www.xwiki.org/rel/tags 当前资源关联标签列表的表示形式。
http://www.xwiki.org/rel/tag 一个标签的表现形式。
http://www.xwiki.org/rel/search 一个搜索资源的表现形式。
http://www.xwiki.org/rel/syntaxes 一个语法资源的表现形式。

关系定义为URI为了是提供一个命名空间。目前这些URI不链接到真正的网页，但是，在未来，他们可能指向实际网页（或其他类型的representation）的语义描述。

"超媒体应用状态引擎（HATEOAS）"图

为了更好地了解资源之间的关系，你可能需要看到所有XWiki的RESTful API中可用的资源和它们之间的关系图。在该图中，节点表示资源类别的URI templates。边缘是一些链接，你可能会发现一个给定资源的representation，和其相关的关系。

该图通过从API入口点开始，客户端可以导航并只是通过下列中的表示中提供的链接（和通过知道它们的语义）发现的所有资源。这正是如何生成该图的方式。

与XWiki RESTful API交互

XWiki的RESTful API是通过HTTP访问，原则上你可以使用所有够“讲”HTTP的客户端能与它交互。甚至web浏览器！
如果你想编写更复杂的程序，你可以下载一个HTTP库用你最喜爱的语言（例如，http://hc.apache.org/）。

Java用户可能会利用JAXB框架及其XJC binding compiler，根据XML Schema直接生成领域对象模型，并使用它们用于序列化和反序列化XML表示形式。

如果你使用这种方法（Apache HTTP Client + JAXB），你会发现自己写一些像这样的代码：

import javax.xml.bind.JAXBContext;
import javax.xml.bind.Unmarshaller;

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.GetMethod;
import org.xwiki.rest.model.jaxb.Page;

...
HttpClient httpClient = new HttpClient();
JAXBContext context = JAXBContext.newInstance("org.xwiki.rest.model.jaxb");
Unmarshaller unmarshaller = context.createUnmarshaller();

GetMethod getMethod = new GetMethod("http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/WebHome");
getMethod.addRequestHeader("Accept", "application/xml");
httpClient.executeMethod(getMethod);

Page page = (Page) unmarshaller.unmarshal(getMethod.getResponseBodyAsStream());

然后你将有所有关于Main.WebHome页面信息的Page对象，而不需要直接处理XML。

由于有各种各样的HTTP框架，我们无法提供所有有关使用他们的一个完整的教程。但是，为了向你展示如何与XWiki RESTful API交互，我们将使用curl：一个标准的命令行HTTP客户端，来发送HTTP请求。

如果使用curl，前面的例子将是：

$ curl http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/WebHome
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<page xmlns="http://www.xwiki.org">
<link rel="http://www.xwiki.org/rel/space" href="http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main"/>
        ...

认证

XWiki REST API支持两种类型的身份验证：

  • HTTP BASIC Auth: 提供授权的HTTP头的凭据
  • XWiki session: 如果你登录的XWiki并使用通过认证机制所提供的cookie，你也将被XWiki RESTful API认证。这是很用的，例如，当你使用Javascript用浏览器的XMLHttpRequest对象进行交互。

如果你不提供任何凭据，XWiki RESTful API将把你作为一个XWiki.Guest用户。

所以，如果访问Main.PrivatePage，通过以下方式： 

$ curl -v http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/PrivatePage
...
< HTTP/1.1 401 Unauthorized
...

你会得到一个未经授权的响应。

相反，通过管理员凭据来获得实际的页面，如下：

$ curl -u Admin:admin http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/PrivatePage
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<page xmlns="http://www.xwiki.org">
<link rel="http://www.xwiki.org/rel/space" href="http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main"/>
...
<content>Only admin can see this</content>
</page>

发送representation

许多资源是可以修改的，所以你可以发送representation来改变这些资源（例如，页面）的状态。
所有可修改的资源接受符合XML Schema定义的XML representation。然而，一些其他的representation也可能被接受（见下文）。 

资源更新通常是通过使用PUT方法来完成，而资源创建是通过PUT或POST完成。

例如，创建一个页面，你可以按照下面方式操作：

$ curl -u Admin:admin -X PUT --data-binary "@newpage.xml" -H "Content-Type: application/xml" http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/NewPage
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<page xmlns="http://www.xwiki.org">
<link rel="http://www.xwiki.org/rel/space" href="http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main"/>
        ...
       <version>1.1</version>
<majorVersion>1</majorVersion>
<minorVersion>1</minorVersion>
<created>2009-03-21+01:00</created>
<creator>XWiki.Admin</creator>
<modified>2009-03-21+01:00</modified>
<modifier>XWiki.Admin</modifier>
<content>This is a new page</content>
</page>

其中，newpage.xml是一个XML文件包含 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<page xmlns="http://www.xwiki.org">     
       <title>Hello world</title>
       <syntax>xwiki/2.0</syntax>
       <content>This is a new page</content>
</page>

该页面已创建并可以访问。随后使用PUT请求到该页面的URI将是修改其内容。

当更新或创建一个页面时，你可以在XML中指定的三要素标题，语法和内容的子集。
例如，如果你只是想更改标题，就只要指定标题元素就足够了。当前内容和页面的语法将保持不变。

解决浏览器限制

正如前面所说的，通过使用浏览器的XMLHttpRequest对象发送信息。但是，目前许多浏览器仅支持GET和POST方法，所以这是不可能的发送，例如，PUT请求。为了解决这个限制，你可以通过指定URI查询字符串的方法参数来替代HTTP方法。

在前面的例子，如果你发送POST请求：http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/NewPage?method=PUT它将会被解释为一个实际的PUT请求。

这种覆盖机制允许使用任何浏览器与XWiki RESTful API交互。

PUT vs POST

在下面的部分，你会看到，有时资源通过使用PUT，有时使用POST创建。总的原则是，如果客户端负责选择资源URI，使用PUT。如果是服务端承担这责任，则使用POST。

为了能更清楚了解，当一个客户端想要创建一个页面，它知道该页面应该去哪里，所以它能够与目标URI进行通信。使用PUT。

一个客户端，与此相反，不能预先知道评论URI是什么，因为评论URI包含评论的ID并且由服务器生成此信息。在这种情况下，客户端将执行POST。

XWiki RESTful API文档

在本节中，你会发现整个XWiki REST API的文档。

application/xml representations指XML Schema定义。

资源的URI使用URI templates指定。括号内的元素是形式参数，并应实例化到实际值来检索相关的资源。

Root资源

默认情况下，所有资源的RESTful API都源于以下URI: http://server:port/xwiki/rest/ (取决于XWiki运行在哪里)

/

  • HTTP Method: GET
    • Media types:
      • application/xml (XWiki元素)
    • Description: 获取包含有关服务器根信息描述（目前返回XWiki产品版本）。
    • Status codes:
      • 200: 如果请求是成功的。

/syntaxes

  • HTTP Method: GET
    • Media types:
      • application/xml (Syntaxes元素)
    • Description: XWiki实例支持的语法列表。
    • Status codes:
      • 200: 如果请求是成功的。

/wikis

  • HTTP Method: GET
    • Media types:
      • application/xml (Wikis元素)
    • Description: XWiki实例可用的wiki列表。除非wiki被构成为一个多租户，这个列表通常是一个单一元素'XWiki'。
    • Status codes:
      • 200: 如果请求是成功的。

/wikis/query?q={query}&wikis=wikiList[&distinct={true,false}][&order={asc,desc}][&start=n][&number=n][&prettyNames={true,false}]

  • HTTP Method: GET
    • Media types:
      • application/xml (SearchResults元素)
    • Description: 搜索资源（页面和附件）：
      • [6.4开始]使用SOLR(SOLR查询模块处理)，wikis参数内wiki用逗号隔开。 
      • [6.4以前]使用Lucene(Lucene插件处理)，wikis参数内wiki用逗号隔开。 
    • Status codes:
      • 200: 如果请求是成功的。

/wikis/{wikiName}

  • HTTP Method: GET
    • Media types:
      • application/xml (Wiki元素)
    • Description: 关于wiki信息
    • Status codes:
      • 200: 如果请求是成功的。
  • HTTP Method: POST
    • Accepted Media types:
      • octet/stream (一个XAR文件)
    • Media types:
      • application/xml (Wiki元素)
    • Query parameters
      • backup={true/false} - 导入XAR作为一个备用XAR
      • history={RESET/REPLACE/ADD} - 历史导入
    • Description: 在一个wiki导入一个XAR。
    • Status codes:
      • 200: 如果请求是成功的。

/wikis/{wikiName}/search?q={keywords}[[&scope={name,content,title,objects}...]&start=n][&number=n][&orderField=field&order={asc,desc}][distinct={true,false}][&prettyNames={true,false}]

  • HTTP Method: GET
    • Media types:
      • application/xml (SearchResults元素)
    • Description: 展示页面和对象在指定{scope}下包含{keywords}的列表。多个范围可以指定。搜索结果是相对于整个{wikiName}
    • Status codes:
      • 200: 如果请求是成功的。

/wikis/{wikiName}/query?q={query}&type={hql,xwql,lucene,solr}[&distinct={true,false}]~[&order={asc,desc}][&start=n][&number=n][&prettyNames={true,false}][&className=className]

  • HTTP Method: GET
    • Media types:
      • application/xml (SearchResults元素)
    • Description: 允许在给定的{wikiName}执行HQL, XWQL, Lucene or SOLR 查询。q参数中包含相应的查询。查看在Velocity的HQL查询例子, XWiki查询语言规范, Lucene插件和SOLR查询API例子。如果类型是hql和指定className，其结果也将包含相应类的第一个对象的数据。
    • Status codes:
      • 200: 如果请求是成功的。

/wikimanager (此资源只可用于当使用XWiki Enterprise Manager)

  • HTTP Method: POST
    • Accepted Media types:
      • application/xml (Wiki元素)
    • Media types:
      • application/xml (Wiki元素)
    • Query parameters
      • template  - 用于初始化wiki的wiki模板
      • history={RESET/REPLACE/ADD} - 历史导入
    • Description: 创建一个新的wiki。
    • Status codes:
      • 200: 如果请求是成功的。

空间资源

/wikis/{wikiName}/spaces[?start=offset&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (Spaces元素)
    • Description: 检索在{wikiName}wiki下可用空间列表。
    • Status codes:
      • 200: 如果请求是成功的。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/search?q={keywords}[[&scope={name,content,title,objects}...]&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (Search results元素)
    • Description: 在指定{scope}下包含{keywords}的页面和对象列表。多个范围可以指定。搜索结果是相对于空间{spaceName}
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

页面资源

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages[?start=offset&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (Pages元素)
    • Description: 空间{spaceName}下页面清单
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}[?prettyNames={true,false}&objects={true,false}&class={true,false}&attachments={true,false}]

  • HTTP Method: GET
    • Media types:
      • application/xml (Page元素)
    • Query parameters
      • prettyNames: 返回了各种文档信息的名称（如作者名称等）。默认情况下禁用。
      • objects: [7.3M1开始] 返回对象。默认情况下禁用。
      • class: [7.3M1开始] 返回类。默认情况下禁用。
      • attachments: [7.3M1开始] 返回附件的元数据。默认情况下禁用。
    • Description: 
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。


  • HTTP Method: PUT
    • Accepted Media types:
      • application/xml (Page元素)
      • text/plain (只有页面内容)
      • application/x-www-form-urlencoded (允许字段名称：title，parent，hidden[从7.3开始]，content)
    • Media types:
      • application/xml (Page元素)
    • Description: 创建或者更新一个页面。
    • Status codes:
      • 201: 如果页面被创建。
      • 202: 如果页面被更新。
      • 304: 如果没有被修改的页面。
      • 401: 如果用户没有被授权。


  • HTTP Method: DELETE
    • Media types:
      • application/xml (Page元素)
    • Description: 删除页面。
    • Status codes:
      • 204: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/history[?start=offset&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (History元素)
    • Description: 给定页面的所有版本的列表。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/history/{version}

  • HTTP Method: GET
    • Media types:
      • application/xml (Page元素)
    • Description: {version}版本下的页面
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/translations[?start=offset&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (Translations元素)
    • Description: 页面可翻译列表
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/translations/{language}

  • HTTP Method: GET
    • Media types:
      • application/xml (Page元素)
    • Description: 给定{language}的页面。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。


  • HTTP Method: PUT
    • Accepted Media types:
      • application/xml (Page元素)
      • text/plain (Only page content)
      • application/x-www-form-urlencoded (允许字段名称：title，parent，content)
    • Media types:
      • application/xml (Page元素)
    • Description: 创建或更新页面的翻译
    • Status codes:
      • 201: 如果页面被创建。
      • 202: 如果页面被更新。
      • 304: 如果页面没有被修改。
      • 401: 如果用户没有被授权。


  • HTTP Method: DELETE
    • Media types:
      • application/xml (Page元素)
    • Description: 删除页面翻译。
    • Status codes:
      • 204: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/translations/{language}/history

  • HTTP Method: GET
    • Media types:
      • application/xml (History元素)
    • Description: 给定{language}页面的所有可用版本的列表。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/translations/{lang}/history/{version}

  • HTTP Method: GET
    • Media types:
      • application/xml (Page元素)
    • Description: 一个给定的{language}给定{version}的页面。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/children

  • HTTP Method: GET
    • Media types:
      • application/xml (Pages元素)
    • Description: 给定页面的孩子列表。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/pages[?name=paneName&space=spaceName&author=authorName]

  • HTTP Method: GET
    • Media types:
      • application/xml (Pages元素)
    • Description: wiki{wikiName}下页面列表。过滤器可以设置为名称，空间或作者。该资源可以用于搜索在一个wiki的页面。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

标签资源

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/tags

  • HTTP Method: GET
    • Media types:
      • application/xml (Tags元素)
    • Description: 页面标签列表。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。


  • HTTP Method: PUT
    • Accepted Media types:
      • application/xml (Tag元素)
      • text/plain 
      • application/x-www-form-urlencoded (允许字段名称：tag)
    • Media types:
      • application/xml (Tags元素)
    • Description: 向页面添加一个tag。
    • Status codes:
      • 202: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/tags

  • HTTP Method: GET
    • Media types:
      • application/xml (Tags元素)
    • Description: 所有可用的标签列表。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/tags/{tag1}[,{tag2},{tag3}...][?start=offset&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (Pages元素)
    • Description: 具有指定标签的页面列表。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

评论资源

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/comments[?start=offset&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (Comments元素)
    • Description: 一个给定页面的评论列表
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。


  • HTTP Method: POST
    • Accepted Media types:
      • application/xml (Comment元素)
      • text/plain
      • application/x-www-form-urlencoded  - 允许字段名：text，replyTo（回复评论的对象数量，从XE2.3开始）
    • Media types:
      • application/xml (Comment元素)
    • Description: 给定页面上创建评论
    • Status codes:
      • 201: 如果评论被创建。（Location头将包含已创建评论的URI）。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/comments/{commentId}

  • HTTP Method: GET
    • Media types:
      • application/xml (Comment元素)
    • Description: 一个页面特定评论
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/history/{version}/comments

  • HTTP Method: GET
    • Media types:
      • application/xml (Comments元素)
    • Description: 一个给定{version}页面的评论列表。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/history/{version}/comments/{commentId}

  • HTTP Method: GET
    • Media types:
      • application/xml (Comment元素)
    • Description: 一个给定{version}页面的评论。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

附件资源

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/attachments[?start=offset&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (Attachments元素)
    • Description: 给定页面的附件列表
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/attachments/{attachmentName}

  • HTTP Method: GET
    • Media types:
      • 与附件media类型相同。
    • Description: 一个给定页面为{attachmentName}的附件
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。


  • HTTP Method: PUT
    • Accepted media types:
      • /
    • Media types:
      • application/xml (AttachmentSummary元素)
    • Description: 在给定页面创建一个为{attachmentName}的附件
    • Status codes:
      • 201: 如果附件被创建。
      • 202: 如果附件被更新。
      • 401: 如果用户没有被授权。


  • HTTP Method: DELETE
    • Media types: 
    • Description: 在给定页面上删除为{attachmentName}的附件。
    • Status codes:
      • 204: 如果附件被删除。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/history/{version}/attachments[?start=offset&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (Attachments元素)
    • Description: 给定页面{version}的附件列表。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/history/{version}/attachments/{attachmentName}

  • HTTP Method: GET
    • Media types:
      • 与附件media类型相同。
    • Description: 给定页面{version}的为{attachmentName}附件
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/attachments/{attachmentName}/history

  • HTTP Method: GET
    • Media types:
      • application/xml (Attachments元素)
    • Description: {attachmentName}附件下可用版本列表
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/attachments/{attachmentName}/history/{version}

  • HTTP Method: GET
    • Media types:
      • 与附件media类型相同。
    • Description: 给定{version}的{attachmentName}附件
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/attachments[?name=attachmentName&page=pageName&author=authorName&types=attachmentTypeList&start=offset&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (Attachments元素)
    • Description: 给定{spaceName}下页面的附件列表。过滤器可以设置为名称, 页面, 作者或者类型(逗号分隔)。该资源可以用于在一个空间搜索附件。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/attachments[?name=attachmentName&page=pageName&space=spaceName&author=authorName&types=attachmentTypeList&start=offset&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (Attachments元素)
    • Description: 给定{wikiName}下页面的附件列表。过滤器可以设置为名称, 页面, 空间, 作者或者类型(逗号分隔)。该资源可以用于在一个wiki搜索附件。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

对象资源

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/objects[?start=offset&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (Objects元素)
    • Description: 页面相关联的对象列表。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。


  • HTTP Method: POST
    • Accepted media types:
      • application/xml (Object元素)
      • application/x-www-form-urlencoded (a set of property#name=value pairs representing properties and a field className)
    • Media types:
      • application/xml (Object元素)
    • Description: 创建一个对象。
    • Status codes:
      • 201: 如果对象被创建（Location头将包含新创建对象的URI）。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/objects/{className}[?start=offset&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (Objects元素)
    • Description: 一个页面给定{className}的关联对象的列表。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/objects/{className}/{objectNumber}

  • HTTP Method: GET
    • Media types:
      • application/xml (Object元素)
    • Description: 一个页面给定{className}的{objectNumber}对象。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。


  • HTTP Method: PUT
    • Accepted media types:
      • application/xml (Object元素)
      • application/x-www-form-urlencoded (a set of property#name=value pairs representing properties)
    • Media types:
      • application/xml (Object元素)
    • Description: 修改object属性。
    • Status codes:
      • 202: 如果对象被更新。
      • 401: 如果用户没有被授权。


  • HTTP Method: DELETE
    • Media types: 
    • Description: 删除对象。
    • Status codes:
      • 204: 如果对象被删除。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/objects/{className}/{objectNumber}/properties

  • HTTP Method: GET
    • Media types:
      • application/xml (Properties元素)
    • Description: 给定页面的{className}类{objectNumber}对象的属性。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/objects/{className}/{objectNumber}/properties/{propertyName}

  • HTTP Method: GET
    • Media types:
      • application/xml (Properties元素)
    • Description: 给定页面的{className}对象类型{objectNumber}的{propertyname}属性。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。


  • HTTP Method: PUT
    • Accepted media types:
      • application/xml (Property元素)
      • text/plain
      • application/x-www-form-urlencoded (a field property#name=value pairs representing a property)
    • Media types:
      • application/xml (Property元素)
    • Description: 修改对象属性。
    • Status codes:
      • 202: 如果对象被更新。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/history/{version}/objects[?start=offset&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (Objects元素)
    • Description: 一个页面给定{version}下的关联对象列表。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/history/{version}/objects/{className}/{objectNumber}

  • HTTP Method: GET
    • Media types:
      • application/xml (Object元素)
    • Description: 一个页面给定{version}下{className}对象类型{objectNumber}的对象。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/history/{version}/objects/{className}/{objectNumber}/properties

  • HTTP Method: GET
    • Media types:
      • application/xml (Properties元素)
    • Description: 一个页面给定{version}下{className}对象类型{objectNumber}的对象属性。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages/{pageName}/history/{version}/objects/{className}/{objectNumber}/properties/{propertyName}

  • HTTP Method: GET
    • Media types:
      • application/xml (Properties元素)
    • Description: 一个页面给定{version}下{className}对象类型{objectNumber}对象的{propertyname}属性。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/class/{className}/objects

  • HTTP Method: GET
    • Media types:
      • application/xml (Objects元素)
    • Description: 给定{className}下所有对象列表。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

类资源

/wikis/{wikiName}/classes[?start=offset&number=n]

  • HTTP Method: GET
    • Media types:
      • application/xml (Classes元素)
    • Description: 在wiki{wikiName}中定义的所有类的列表
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/classes/{className}

  • HTTP Method: GET
    • Media types:
      • application/xml (Class元素)
    • Description: {className}定义
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/classes/{className}/properties

  • HTTP Method: GET
    • Media types:
      • application/xml (Properties元素)
    • Description: 类{className}的属性。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

/wikis/{wikiName}/classes/{className}/properties/{property}

  • HTTP Method: GET
    • Media types:
      • application/xml (Property元素)
    • Description: 类{className}的{property}属性。
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

作业资源

作业是一个ID(jobId)，它是一个字符串标识。在REST URL,必须通过/分隔字符串来表示ID。(如: refactoring/delete/11451).

/jobstatus/{jobId} Since 7.2M3

  • HTTP Method: GET
    • Media types:
      • application/xml (JobStatus元素)
    • Description: 作业状态
    • Status codes:
      • 200: 如果请求是成功的。
      • 404: 如果找不到作业状态。

/joblog/{jobId}[?level={error,warn,info,debug,trace}][?fromLevel={error,warn,info,debug,trace}] Since 7.2M3

  • HTTP Method: GET
    • Media types:
      • application/xml (JobLog元素)
    • Description: job日志
    • Status codes:
      • 200: 如果请求是成功的。
      • 404: 如果找不到作业状态。

其他资源

/wikis/{wikiName}/modifications[?start=offset&number=n&date=t]

  • HTTP Method: GET
    • Media types:
      • application/xml (Modifications元素)
    • Description: wiki{wikiName}从时间t（t以毫秒为单位，起始日期从1970年开始）开始的最近修改列表
    • Status codes:
      • 200: 如果请求是成功的。
      • 401: 如果用户没有被授权。

自定义资源

可以很容易地在你的wiki注册一个org.xwiki.rest.XWikiResourceJava组件来添加REST资源（参见组件指南）。

package org.xwiki.contrib.rest;

import javax.ws.rs.DefaultValue;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

import org.xwiki.component.annotation.Component;
import org.xwiki.rest.XWikiResource;

@Component("org.xwiki.contrib.rest.HelloWordResource")
@Path("/myresources/{myresourcename}")
class HelloWorldResource extends XWikiResource {
 @GET
 public String get(@PathParam("myresourcename")  @DefaultValue("world") String myresourcename)
 {
   return "Hello " + myresourcename;
 }
}

组件的名称必须是全名。

你可以在此页面找到更多的例子。

从4.3M2发布开始，基于REST API模块已被重构，因此现在资源的声明是在一个单独的模块提供。
这意味着所有的关于资源的信息，即URI路径，支持的方法，查询参数，等等，都可以提供给模块开发者而无需引入REST Server模块。

客户端访问/使用REST API则可以声明对xwiki-platform-rest-api的依赖，然后就可以与它交互信息。有两个使用用例：

  • 另一个平台模块想要对现有资源生成带有链接响应。
  • HTTP客户端向RESTful API发出请求。

xwiki-platform-rest-api模块也可以看作是REST API的权威参考。

为资源生成一个REST URL

如果你需要生成一个REST URL字符串作为一个脚本中的资源，你可以使用REST脚本服务：

## Return a relative URL String unless the reference wiki is different from the current wiki
$services.rest.url($entityReference)

## Force returning an external form URL String, false as second parameter would have the same effect that the previous call
$services.rest.url($entityReference, true)

其中$entityReference 可能是：

  • 一个文档
  • 一个空间

我们计划在未来增加更多的实体支持（对象，类等等）。

使用RESTful API

使用RESTful API基础教程

请参阅Fabio Mancinelli博客写的教程。

创建一个XWiki对象

在这个例子中，我们将使用curl作为HTTP客户端。

想象一下，你要创建Test.Test页面的一个XWiki.TestClass类对象，假设类有一个名为text的属性。

因此，在命令行中，你可以按照以下来操作：

$ curl -u Admin:admin
       -X POST
       -H "Content-type: application/xml"
       -H "Accept: application/xml"
       -d "@test.xml"  
       http://localhost/xwiki/rest/wikis/xwiki/spaces/Test/pages/Test/objects

test.xml内容：

<object xmlns="http://www.xwiki.org">
<className>XWiki.TestClass</className>
<property name="text">
  <value>Whatever you want to put here</value>
</property>
</object>

另外，你可以使用更简洁application/x-www-form-urlencoded格式：

$ curl -u Admin:admin
       -X POST
       -H "Content-type: application/x-www-form-urlencoded"
       -H "Accept: application/xml"
       -d "@test.txt"
       http://localhost/xwiki/rest/wikis/xwiki/spaces/Test/pages/Test/objects

test.txt包含如下内容：

className=XWiki.TestClass&property#test=Whatever+you+want

或者，更好的，你可以直接使用curl指定这些参数
使用多个-d参数：

$ curl -u Admin:admin
       -X POST -H "Content-type: application/x-www-form-urlencoded"
       -H "Accept: application/xml"
       -d "className=XWiki.TestClass"
       -d "property#test=Whatever you want"
       http://localhost/xwiki/rest/wikis/xwiki/spaces/Test/pages/Test/objects

第二种方法的优点是，如果你发送一个文件，curl会处理内容的URL编码。

备注:

  • 在application/x-www-form-urlencoded格式"property#"是用于区分对象属性值的一个前缀。例如，如果我们有类名className=XYZ&Text=FOO我们会有一个模糊的className因为我们无法理 className是对象的属性设置XYZ还是描述对象本身的属性（即，其元数据，如className）。通过有property#前缀，问题就能得到解决。
  • 当客户端需要理解包含在对象(例如，当他们想要显示它)数据类型时，返回一个对象(即,所有<attribute>元素) 的信息是有用的。当创建一个对象时，它们是没有必要的，因为该系统已经有这个信息。这就是为什么要发送的XML是较小的。实际需要的唯一信息是<className>和一组<property name="..."><value>元素。
  • 你知道你发送的xml需要什么类型的信息吗？你可以通过使用类描述URI发现。如果你进入 http://localhost:8080/xwiki/rest/wikis/xwiki/classes你将获得在wiki中定义的所有类的列表。通过查看此内容你可以了解每一个类定义的属性。这样一来，你就会知道发送的XML元素的<property><value>是什么。

例子

获取用户列表

由于用户存储为对象，你可以用一个搜索类型为XWiki.XWikiUsers。例如：

http://<server>/xwiki/rest/wikis/query?q=object:XWiki.XWikiUsers

相关推荐