Changes for page REST API

Last modified by Thomas Mortagne on 2024/03/12

<
From version < 9.1 >
edited by Silvia Macovei
on 2009/10/06
To version < 9.4 >
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,22 +51,22 @@
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 64  
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!
64 +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}}
... ... @@ -113,8 +113,8 @@
113 113  ...
114 114  {{/code}}
115 115  
116 -You will get an Unathorized empty response.
117 -<p/>
115 +You will get an Unauthorized empty response.
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  
... ... @@ -178,13 +178,13 @@
178 178  
179 179  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.
180 180  
181 -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 more clear, when a client wants to create a page it knows **where** that page should go, so it is able to communicate to the server the target URI. In this situation PUT is used.
182 182  
183 -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.
181 +A client, on the contrary, cannot know beforehand what will be the URI of a comment, when 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.
184 184  
185 185  == XWiki RESTful API Documentation ==
186 186  
187 -In this section you will find the documentation of the whole XWiki RESTful API.
185 +In this section you will find the documentation for the whole XWiki RESTful API.
188 188  
189 189  **application/xml** representations refers to the XML Schema Definition at the following location: [[http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-rest/src/main/resources/xwiki.rest.model.xsd]]
190 190  

Get Connected