Changes for page REST API

Summary

• Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

...	...	@@ -1,6 +1,6 @@
1	1	= The XWiki RESTful API =
2	2
3		-XWiki provides fine-grain access to virtually every element through an API that is based on HTTP semantics, i.e. a RESTful API. In this page you will find all the details to take advantage of this API and the instructions to use it at its full potential.
	3	+XWiki provides fine-grain access to virtually every element through an API that is based on HTTP semantics, i.e., a RESTful API. In this page you will find all the details to take advantage of this API and the instructions to use it at its full potential.
4	4
5	5	== Dataset ==
6	6
...	...	@@ -10,13 +10,13 @@
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.
...	...	@@ -68,7 +68,7 @@
68	68
69	69	If you use this approach (Apache HTTP Client + JAXB) you will find yourself writing some code like this:
70	70
71		-{{code}}
	71	+{{code language="none"}}
72	72	HttpClient httpClient = new HttpClient();
73	73	JAXBContext context = JAXBContext.newInstance("model.package");
74	74	unmarshaller = context.createUnmarshaller();
...	...	@@ -86,7 +86,7 @@
86	86
87	87	By using curl, the previous example would have been:
88	88
89		-{{code}}
	89	+{{code language="none"}}
90	90	$ curl http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/WebHome
91	91	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
92	92	<page xmlns="http://www.xwiki.org">
...	...	@@ -105,7 +105,7 @@
105	105
106	106	So if you have, let's say a Main.PrivatePage, and you try to do:
107	107
108		-{{code}}
	108	+{{code language="none"}}
109	109	$ curl -v http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/PrivatePage
110	110	...
111	111	< HTTP/1.1 401 Unauthorized
...	...	@@ -116,7 +116,7 @@
116	116
117	117	On the contrary, by specifying Admin credentials you gain access to the actual page:
118	118
119		-{{code}}
	119	+{{code language="none"}}
120	120	$ curl -u Admin:admin http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/PrivatePage
121	121	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
122	122	<page xmlns="http://www.xwiki.org">
...	...	@@ -135,7 +135,7 @@
135	135
136	136	For example, in order to create a page you might do the following:
137	137
138		-{{code}}
	138	+{{code language="none"}}
139	139	$ curl -u Admin:admin -X PUT -d "@newpage.xml" -H "Content-Type: application/xml" http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/NewPage
140	140	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
141	141	<page xmlns="http://www.xwiki.org">
...	...	@@ -154,7 +154,7 @@
154	154
155	155	Where newpage.xml is an XML file containing
156	156
157		-{{code}}
	157	+{{code language="none"}}
158	158	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
159	159	<page xmlns="http://www.xwiki.org">
160	160	<title>Hello world</title>
...	...	@@ -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