Change comment:
There is no comment for this version
Summary
-
Page properties (1 modified, 0 added, 0 removed)
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><link></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×tamp=t]]====766 +==== /wikis/{wikiName}/modifications[?start~=offset&number~=n×tamp~=t] ==== 773 773 774 774 * **HTTP Method:** GET 775 775 ** **Media types:**