Changes for page REST API

Last modified by Thomas Mortagne on 2024/03/12

<
From version < 10.2 >
edited by Silvia Macovei
on 2009/10/08
To version < 10.4 >
edited by Silvia Macovei
on 2009/10/08
>
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -6,17 +6,17 @@
6 6  
7 7  This section contains a brief and high-level description of the XWiki data set that should serve as a basis for presenting resources and their associated operations.
8 8  
9 -XWiki has **pages** organized in **spaces**. Each **page** is available in multiple **versions** (its **history**) and **translations**. Translated pages have their own **versions** and **history** which are independent. Each page might have **attachments**. Each attachment has its own **history**. Attachments are shared among all the different translations of a page (i.e., the same set of attachments is the same regardless of the page language). Pages can have one or more **objects**. Objects are instances of a **class** that contains a set of **properties**. Some object might be directly exposed as first class entities, such as **comments** and **tags**. Objects, as attachments, are shared among all page translations.
9 +XWiki has **pages** organized in **spaces**. Each **page** is available in multiple **versions** (its **history**) and **translations**. Translated pages have their own **versions** and **history** which are independent. Each page might have **attachments**. Each attachment has its own **history**. Attachments are shared among all the different translations of a page (i.e., the same set of attachments is the same regardless of the page language). Pages can have one or more **objects**. Objects are instances of a **class** that contains a set of **properties**. Some objects might be directly exposed as first class entities, such as **comments** and **tags**. Objects, as attachments, are shared among all page translations.
10 10  
11 11  == Understanding resources and representations ==
12 12  
13 -"An important concept in REST is the existence of resources (sources of specific information), each of which is referenced with a global identifier (e.g., a URI in HTTP). In order to manipulate these resources, components of the network (user agents and origin servers) communicate via a standardized interface (e.g., HTTP) and exchange representations of these resources (the actual documents conveying the information)." ([[Wikipedia>>http://en.wikipedia.org/wiki/Representational_State_Transfer#REST.27s_central_principle:_resources]])
13 +"An important concept in REST is the existence of resources (sources of specific information), each of which is referenced with a global identifier (e.g., an URI in HTTP). In order to manipulate these resources, components of the network (user agents and origin servers) communicate via a standardized interface (e.g., HTTP) and exchange representations of these resources (the actual documents conveying the information)." ([[Wikipedia>>http://en.wikipedia.org/wiki/Representational_State_Transfer#REST.27s_central_principle:_resources]])
14 14  
15 15  Resources in XWiki are pages, attachments, objects, properties, spaces, and all the //things// we described in the previous section. XWiki has a default way of conveying the information about these resources, i.e., by providing well defined XML representations that contain all the information associated to the resource in an XML format. This format is described using an XML Schema Definition file that can be found here: [[http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-rest/src/main/resources/xwiki.rest.model.xsd]]
16 16  
17 -Of course the same resource can be represented in many different ways. When it is the case, this will be documented.
17 +Of course the same resource can be represented in many different ways. This is yet to be documented.
18 18  
19 -Another important aspect of representations is that they contain useful information for linking related resources. This is a realization of the //Hypermedia As The Engine Of The Application State (HATEOAS)// principle. In XML representations this information is conveyed through the <tt>&lt;link&gt;</tt> tag. This tag has two important parameters: **rel** and **href**. **rel** specifies the "semantics" of the link, while **href** is the URI of the linked resource.
19 +Another important aspect of representations is that they contain useful information for linking related resources. This is a realization of the //Hypermedia As The Engine Of The Application State (HATEOAS)// principle. In XML representations this information is conveyed through the ##<link>## tag. This tag has two important parameters: **rel** and **href**. **rel** specifies the "semantics" of the link, while **href** is the URI of the linked resource.
20 20  
21 21  For example, in the representation of a page, we can have links to the comments, tags, attachments which are independent resources associated to the current page. These links are provided in the XML representation of a page and allow a client to navigate to related resources... Like we do every day when we click on a link in a web page.
22 22  
... ... @@ -29,7 +29,7 @@
29 29  |=Rel|=Semantics
30 30  |http://www.xwiki.org/rel/wikis|The representation containing the list of virtual wikis.
31 31  |http://www.xwiki.org/rel/spaces|The representation containing the list of spaces in a wiki.
32 -|http://www.xwiki.org/rel/pages|The representations containing the list of pages in a space.
32 +|http://www.xwiki.org/rel/pages|The representation containing the list of pages in a space.
33 33  |http://www.xwiki.org/rel/translation|The representation containing a translation of a page.
34 34  |http://www.xwiki.org/rel/page|The representation for a page.
35 35  |http://www.xwiki.org/rel/space|The representation for a space.
... ... @@ -166,17 +166,17 @@
166 166  
167 167  === Overcoming browser limitations ===
168 168  
169 -As said before, it could be useful to send information by using browser's XmlHttpRequest objects. But currently many browsers only support GET and POST methods, so it is impossible to send, for example, PUT requests. In order to overcome this limitation you can override the HTTP Method by specifying a <tt>method</tt> parameter in the URI query string.
169 +As said before, it could be useful to send information by using browser's XmlHttpRequest objects. However, currently many browsers only support GET and POST methods, so it is impossible to send, for example, PUT requests. In order to overcome this limitation you can override the HTTP Method by specifying a ##method## parameter in the URI query string.
170 170  
171 -In the previous example, if you send a POST request to the <tt>http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/NewPage?method=PUT</tt> it will be interpreted as if it were an actual PUT request.
171 +In the previous example, if you send a POST request to the ##[[http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/NewPage?method=PUT]]## it will be interpreted as if it were an actual PUT request.
172 172  
173 173  This overriding mechanism allows the interaction with the XWiki RESTful API by using any kind of browser.
174 174  
175 175  === PUT vs POST ===
176 176  
177 -In the following sections you will see that sometimes resources are created by using PUT and sometimes by using POST. The general principle is that if the client is responsible for choosing the resource URI then PUT is used. If it's the server that bears this responsibility then POST is used.
177 +In the following sections you will see that sometimes resources are created by using PUT and sometimes by using POST. The general principle is that if the client is responsible for choosing the resource URI then PUT is used. If it's the server that bears this responsibility, then POST is used.
178 178  
179 -To be more clear, when a client wants to create a page it knows **where** that page should go, so it is able to communicate the server the target URI. PUT is used.
179 +To be clearer, when a client wants to create a page it knows **where** that page should go, so it is able to communicate the server the target URI. PUT is used.
180 180  
181 181  A client, on the contrary, cannot know beforehand what will be the URI of a comment, since comment URIs contains the ID of the comment and this information is generated by the server. In this case the client will do a POST and the server, in response, will communicate the URI it generated for the newly created comment.
182 182  

Get Connected