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 < 10.1 >
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}}
... ... @@ -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  
... ... @@ -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)
... ... @@ -223,7 +223,7 @@
223 223  
224 224  === Space resources ===
225 225  
226 -==== /wikis/{wikiName}/spaces[[?start=offset&number=n]] ====
222 +==== /wikis/{wikiName}/spaces[?start~=offset&number~=n] ====
227 227  
228 228  * **HTTP Method:** GET
229 229  ** **Media types:**
... ... @@ -232,10 +232,8 @@
232 232  ** **Status codes:**
233 233  *** 200: If the request was successful.
234 234  
235 -==== /wikis/{wikiName}/spaces/{spaceName}/search?q ====
231 +==== /wikis/{wikiName}/spaces/{spaceName}/search?q~={keywords}~[~[&scope~={name,content,title,objects}...~]&number~=n~] ====
236 236  
237 -{keywords}[[[&scope={name,content,title,objects}...]]&number=n] ====
238 -
239 239  * **HTTP Method:** GET
240 240  ** **Media types:**
241 241  *** application/xml (Search results element)
... ... @@ -246,7 +246,7 @@
246 246  
247 247  === Page resources ===
248 248  
249 -==== /wikis/{wikiName}/spaces/{spaceName}/pages[[?start=offset&number=n]] ====
243 +==== /wikis/{wikiName}/spaces/{spaceName}/pages[?start~=offset&number~=n] ====
250 250  
251 251  * **HTTP Method:** GET
252 252  ** **Media types:**
... ... @@ -292,7 +292,7 @@
292 292  *** 204: If the request was successful.
293 293  *** 401: If the user is not authorized.
294 294  
295 -==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history[[?start=offset&number=n]] ====
289 +==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history[?start~=offset&number~=n] ====
296 296  
297 297  * **HTTP Method:** GET
298 298  ** **Media types:**
... ... @@ -312,7 +312,7 @@
312 312  *** 200: If the request was successful.
313 313  *** 401: If the user is not authorized.
314 314  
315 -==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/translations[[?start=offset&number=n]] ====
309 +==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/translations[?start~=offset&number~=n] ====
316 316  
317 317  * **HTTP Method:** GET
318 318  ** **Media types:**
... ... @@ -424,7 +424,7 @@
424 424  *** 200: If the request was successful.
425 425  *** 401: If the user is not authorized.
426 426  
427 -==== /wikis/{wikiName}/tags/{tag1}[[,{tag2},{tag3}...]][[?start=offset&number=n]] ====
421 +==== /wikis/{wikiName}/tags/{tag1}[,{tag2},{tag3}...][?start~=offset&number~=n] ====
428 428  
429 429  * **HTTP Method:** GET
430 430  ** **Media types:**
... ... @@ -436,7 +436,7 @@
436 436  
437 437  === Comments resources ===
438 438  
439 -==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/comments[[?start=offset&number=n]] ====
433 +==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/comments[?start~=offset&number~=n] ====
440 440  
441 441  * **HTTP Method:** GET
442 442  ** **Media types:**
... ... @@ -492,7 +492,7 @@
492 492  
493 493  === Attachments resources ===
494 494  
495 -==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/attachments[[?start=offset&number=n]] ====
489 +==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/attachments[?start~=offset&number~=n] ====
496 496  
497 497  * **HTTP Method:** GET
498 498  ** **Media types:**
... ... @@ -534,7 +534,7 @@
534 534  *** 204: If the attachment was deleted.
535 535  *** 401: If the user is not authorized.
536 536  
537 -==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history/{version}/attachments[[?start=offset&number=n]] ====
531 +==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history/{version}/attachments[?start~=offset&number~=n] ====
538 538  
539 539  * **HTTP Method:** GET
540 540  ** **Media types:**
... ... @@ -576,7 +576,7 @@
576 576  
577 577  === Object resources ===
578 578  
579 -==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/objects[[?start=offset&number=n]] ====
573 +==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/objects[?start~=offset&number~=n] ====
580 580  
581 581  * **HTTP Method:** GET
582 582  ** **Media types:**
... ... @@ -599,7 +599,7 @@
599 599  *** 201: If the object was created (The Location header will contain the URI associated to the newly created object).
600 600  *** 401: If the user is not authorized.
601 601  
602 -==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/objects/{className}[[?start=offset&number=n]] ====
596 +==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/objects/{className}[?start~=offset&number~=n] ====
603 603  
604 604  * **HTTP Method:** GET
605 605  ** **Media types:**
... ... @@ -675,7 +675,7 @@
675 675  *** 202: If the object was updated.
676 676  *** 401: If the user is not authorized.
677 677  
678 -==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history/{version}/objects[[?start=offset&number=n]] ====
672 +==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history/{version}/objects[?start~=offset&number~=n] ====
679 679  
680 680  * **HTTP Method:** GET
681 681  ** **Media types:**
... ... @@ -727,7 +727,7 @@
727 727  
728 728  === Class resources ===
729 729  
730 -==== /wikis/{wikiName}/classes[[?start=offset&number=n]] ====
724 +==== /wikis/{wikiName}/classes[?start~=offset&number~=n] ====
731 731  
732 732  * **HTTP Method:** GET
733 733  ** **Media types:**
... ... @@ -769,7 +769,7 @@
769 769  
770 770  === Other resources ===
771 771  
772 -==== /wikis/{wikiName}/modifications[[?start=offset&number=n&timestamp=t]] ====
766 +==== /wikis/{wikiName}/modifications[?start~=offset&number~=n&timestamp~=t] ====
773 773  
774 774  * **HTTP Method:** GET
775 775  ** **Media types:**

Get Connected