<
From version < 4.1 >
edited by Fabio Mancinelli
on 2009/03/21
To version < 5.1 >
edited by Fabio Mancinelli
on 2009/03/21
>
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -13,12 +13,12 @@
13 13  
14 14  "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])
15 15  
16 -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 a well defined XML representation that contains all the information associated to the resource in an XML format.
16 +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.
17 17  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]
18 18  
19 -Of course, the same resource can be represented in many different way. When it is the case, this will be documented.
19 +Of course the same resource can be represented in many different way. When it is the case, this will be documented.
20 20  
21 -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.
21 +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.
22 22  
23 23  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.
24 24  
... ... @@ -26,7 +26,7 @@
26 26  
27 27  1.1.1 Relations
28 28  
29 -In XML representations the available relations that you might find are the following:
29 +The available relations that you might find in the XML resource representations are the following:
30 30  
31 31  {table}
32 32  Rel | Semantics
... ... @@ -59,18 +59,18 @@
59 59  
60 60  1.1.1 The "HATEOAS" Graph
61 61  
62 -In order to better understand the relations among resources you might have a look at this {attach:graph|file=XWikiHATEOAS.pdf} that pictures all the resources available in the XWiki RESTful API and the relations among them. In this graph, nodes are [URI templates > http://bitworking.org/projects/URI-Templates/spec/draft-gregorio-uritemplate-03.txt] representing classes of resources. Edges are the possible links that you might find in a representation of a given resource and their associated relations.
62 +In order to better understand the relations among resources you might have a look at this {attach:graph|file=XWikiHATEOAS.pdf} that pictures all the resources available in the XWiki RESTful API and the relations among them. In this graph, nodes are [URI templates > http://bitworking.org/projects/URI-Templates/spec/draft-gregorio-uritemplate-03.txt] representing classes of resources. Edges are the possible links that you might find in a representation of a given resource, and their associated relations.
63 63  
64 64  This graph shows that by starting from the API entry-point a client can navigate and discover all the resources just by following the links provided in representations (and by knowing their semantics). This was exactly the way how this graph was generated.
65 65  
66 66  1.1 Interacting with the XWiki RESTful API
67 67  
68 -The XWiki RESTful API is accessible through HTTP so, in principle you can use every client that is capable of "speaking" HTTP in order to interact with it. Even a web browser!
68 +The XWiki RESTful API is accessible through HTTP so, in principle, you can use every client that is capable of "speaking" HTTP in order to interact with it. Even a web browser!
69 69  If you want to write more complex programs you might download an HTTP library for your favorite language (e.g., [http://hc.apache.org/]).
70 70  
71 71  Java users might take advantage of the [JAXB > https://jaxb.dev.java.net] framework and its [XJC binding compiler > https://jaxb.dev.java.net/jaxb20-ea3/docs/xjc.html] in order to generate domain object models directly from the [XML Schema Definition > http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-rest/src/main/resources/xwiki.rest.model.xsd], and use them for serializing and de-serializing XML representations.
72 72  
73 -If you use this approach (Apache HTTP Client + JAXB) you might have to write some code like this:
73 +If you use this approach (Apache HTTP Client + JAXB) you will find yourself writing some code like this:
74 74  
75 75  {code}
76 76  HttpClient httpClient = new HttpClient();
... ... @@ -84,11 +84,11 @@
84 84  Page page = (Page) unmarshaller.unmarshal(getMethod.getResponseBodyAsStream());
85 85  {code}
86 86  
87 -And you will have all the information about the Main.WebHome page in the Page object, without the need of handling the XML directly.
87 +And you will have all the information about the Main.WebHome page in the Page object, without the need of handling XML directly.
88 88  
89 -Because of the wide variety of HTTP frameworks available we don't provide here a full tutorial about using them. However, in order to show you how to interact with the XWiki RESTful API, we will use [curl > http://curl.haxx.se], a standard command line HTTP client that provides an interface to all the functionalities of the HTTP protocol.
89 +Because of the wide variety of HTTP frameworks available we don't provide a full tutorial about using them. However, in order to show you how to interact with the XWiki RESTful API, we will use [curl > http://curl.haxx.se]: a standard command line HTTP client that provides an interface to all the functionalities of the HTTP protocol.
90 90  
91 -In this case, the previous example would have been:
91 +By using curl, the previous example would have been:
92 92  
93 93  {code}
94 94  $ curl http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/WebHome
... ... @@ -100,15 +100,15 @@
100 100  
101 101  1.1.1 Authentication
102 102  
103 -The XWiki RESTful API supports two kinds of authentication:
103 +The XWiki RESTful API supports two types of authentication:
104 104  
105 105  * *HTTP BASIC Auth*: You provide your credentials using the Authorization HTTP header
106 106  
107 107  * *XWiki session*: If you are logged in XWiki and you use the cookies provided by the authentication mechanism, you will also be authenticated to the XWiki RESTful API. This is useful, for example, when you are interacting with the API using the XMLHttpRequest object of a browser using Javascript.
108 108  
109 -If you don't provide your credentials, then the XWiki RESTful API will recognize you as a XWiki.Guest user.
109 +If you don't provide any credentials the XWiki RESTful API will recognize you as a XWiki.Guest user.
110 110  
111 -So, if you have, let's say a Main.PrivatePage, if you try to do:
111 +So if you have, let's say a Main.PrivatePage, and you try to do:
112 112  
113 113  {code}
114 114  $ curl -v http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/PrivatePage
... ... @@ -117,6 +117,8 @@
117 117  ...
118 118  {code}
119 119  
120 +You will get an Unathorized empty response.
121 +
120 120  On the contrary, by specifying Admin credentials you gain access to the actual page:
121 121  
122 122  {code}
... ... @@ -132,7 +132,7 @@
132 132  1.1.1 Sending representations
133 133  
134 134  Many resources are modifiable, so you can send representations in order to change the state of those resources (e.g., pages).
135 -All modifiable resources accepts XML representations that conforms to the [XML Schema Definition > http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-rest/src/main/resources/xwiki.rest.model.xsd]. However, some other representations might be accepted as well (see the following sections).
137 +All modifiable resources accepts XML representations that conform to the [XML Schema Definition > http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-rest/src/main/resources/xwiki.rest.model.xsd]. However, some other representations might be accepted as well (see the following sections).
136 136  
137 137  Resource update is usually done by using the PUT method, while resource creation is done via PUT or POST.
138 138  
... ... @@ -171,13 +171,13 @@
171 171  
172 172  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.
173 173  
174 -So, 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.
176 +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.
175 175  
176 176  This overriding mechanism allows the interaction with the XWiki RESTful API by using any kind of browser.
177 177  
178 178  1.1.1 PUT vs POST
179 179  
180 -In the following sections you will see that sometimes resources are created with PUT and sometimes with POST. The general principle is that if the client is responsible of choosing the resource URI then PUT is used. If it's the server that bears that responsibility then POST is used.
182 +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 of choosing the resource URI then PUT is used. If it's the server that bears this responsibility then POST is used.
181 181  
182 182  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.
183 183  

Get Connected