Summary

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

Details

Page properties

Content

...	...	@@ -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.
...	...	@@ -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