<
From version < 9.1 >
edited by Silvia Macovei
on 2009/10/06
To version < 9.2 >
edited by Silvia Macovei
on 2009/10/06
>
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -16,11 +16,10 @@
16 16  
17 17  Of course the same resource can be represented in many different ways. When it is the case, this will be documented.
18 18  
19 -{{html clean="false" wiki="true"}}
20 20  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 -<p/>
20 +
22 22  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.
23 -<p/>
22 +
24 24  [[image:representation||height="430"]]
25 25  
26 26  === Relations ===
... ... @@ -51,13 +51,13 @@
51 51  |http://www.xwiki.org/rel/tags|The representation of the list of tags associated to the current resource.
52 52  |http://www.xwiki.org/rel/tag|The representation of a tag.
53 53  |http://www.xwiki.org/rel/search|The representation for a search resource.
54 -<p/>
53 +
55 55  Relations are defined as URIs in order to provide a sort of namespace. Currently these URIs are not links to real web pages but, in the future, they might point to descriptions of their semantics on actual web pages (or other kinds of representations).
56 56  
57 57  === The "HATEOAS" Graph ===
58 58  
59 59  In order to better understand the relations among resources you might have a look at this [[graph>>attach: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.
60 -<p/>
59 +
61 61  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.
62 62  
63 63  == Interacting with the XWiki RESTful API ==
... ... @@ -64,9 +64,9 @@
64 64  
65 65  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!
66 66  If you want to write more complex programs you might download an HTTP library for your favorite language (e.g., [[http://hc.apache.org/]]).
67 -<p/>
66 +
68 68  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.
69 -<p/>
68 +
70 70  If you use this approach (Apache HTTP Client + JAXB) you will find yourself writing some code like this:
71 71  
72 72  {{code}}
... ... @@ -82,9 +82,9 @@
82 82  {{/code}}
83 83  
84 84  And you will have all the information about the Main.WebHome page in the Page object, without the need of handling XML directly.
85 -<p/>
84 +
86 86  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.
87 -<p/>
86 +
88 88  By using curl, the previous example would have been:
89 89  
90 90  {{code}}
... ... @@ -101,9 +101,9 @@
101 101  
102 102  * **HTTP BASIC Auth**: You provide your credentials using the Authorization HTTP header
103 103  * **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.
104 -<p/>
103 +
105 105  If you don't provide any credentials the XWiki RESTful API will recognize you as a XWiki.Guest user.
106 -<p/>
105 +
107 107  So if you have, let's say a Main.PrivatePage, and you try to do:
108 108  
109 109  {{code}}
... ... @@ -114,7 +114,7 @@
114 114  {{/code}}
115 115  
116 116  You will get an Unathorized empty response.
117 -<p/>
116 +
118 118  On the contrary, by specifying Admin credentials you gain access to the actual page:
119 119  
120 120  {{code}}
... ... @@ -131,9 +131,9 @@
131 131  
132 132  Many resources are modifiable, so you can send representations in order to change the state of those resources (e.g., pages).
133 133  All modifiable resources accept 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).
134 -<p/>
133 +
135 135  Resource update is usually done by using the PUT method, while resource creation is done via PUT or POST.
136 -<p/>
135 +
137 137  For example, in order to create a page you might do the following:
138 138  
139 139  {{code}}
... ... @@ -168,9 +168,8 @@
168 168  === Overcoming browser limitations ===
169 169  
170 170  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.
171 -<p/>
170 +
172 172  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.
173 -{{/html}}
174 174  
175 175  This overriding mechanism allows the interaction with the XWiki RESTful API by using any kind of browser.
176 176  
... ... @@ -210,10 +210,8 @@
210 210  ** **Status codes:**
211 211  *** 200: If the request was successful.
212 212  
213 -==== /wikis/{wikiName}/search?q ====
211 +==== /wikis/{wikiName}/search?q={keywords}[[&scope={name,content,title,objects}...]&number=n] ====
214 214  
215 -{keywords}[[[&scope={name,content,title,objects}...]]&number=n] ====
216 -
217 217  * **HTTP Method:** GET
218 218  ** **Media types:**
219 219  *** application/xml (SearchResults element)

Get Connected