Wiki source code of The XWiki RESTful API

Version 16.3 by Vincent Massol on 2009/12/17

version	line-number	content
14.2	1	{{box cssClass="floatinginfobox" title="Contents"}}{{toc depth="2"/}}{{/box}}
1.1	2
10.5	3	XWiki provides fine-grain access to virtually every element through an API that is based on HTTP semantics, i.e., a RESTful API. In this page you will find all the details to take advantage of this API and the instructions to use it at its full potential.
1.1	4
16.2	5	By defaut the XWiki RESTful API entrypoint is rooted at the following URI: ##http:~//server:port/xwiki/rest/## (depending on where your XWiki is running)
16.1	6
14.2	7	= Dataset =
1.1	8
	9	This section contains a brief and high-level description of the XWiki data set that should serve as a basis for presenting resources and their associated operations.
	10
10.3	11	XWiki has pages organized in spaces. Each page is available in multiple versions (its history) and translations. Translated pages have their own versions and history which are independent. Each page might have attachments. Each attachment has its own history. Attachments are shared among all the different translations of a page (i.e., the same set of attachments is the same regardless of the page language). Pages can have one or more objects. Objects are instances of a class that contains a set of properties. Some objects might be directly exposed as first class entities, such as comments and tags. Objects, as attachments, are shared among all page translations.
1.1	12
14.2	13	= Understanding resources and representations =
1.1	14
10.4	15	"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., an 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]])
1.1	16
9.1	17	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. 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]]
1.1	18
10.4	19	Of course the same resource can be represented in many different ways. This is yet to be documented.
1.1	20
10.4	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 ##<link>## 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.
9.2	22
1.1	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.
9.2	24
9.1	25	[[image:representation\|\|height="430"]]
1.1	26
14.2	27	== Relations ==
1.1	28
5.1	29	The available relations that you might find in the XML resource representations are the following:
1.1	30
9.1	31	\|=Rel\|=Semantics
15.1	32	\|{{{http://www.xwiki.org/rel/wikis}}}\|The representation containing the list of virtual wikis.
	33	\|{{{http://www.xwiki.org/rel/spaces}}}\|The representation containing the list of spaces in a wiki.
	34	\|{{{http://www.xwiki.org/rel/pages}}}\|The representation containing the list of pages in a space.
	35	\|{{{http://www.xwiki.org/rel/translation}}}\|The representation containing a translation of a page.
	36	\|{{{http://www.xwiki.org/rel/page}}}\|The representation for a page.
	37	\|{{{http://www.xwiki.org/rel/space}}}\|The representation for a space.
	38	\|{{{http://www.xwiki.org/rel/parent}}}\|The representation for the page that is parent of the current resource.
	39	\|{{{http://www.xwiki.org/rel/home}}}\|The representation for the page that is the home of the current resource.
	40	\|{{{http://www.xwiki.org/rel/attachmentData}}}\|The representation of the actual attachment data.
	41	\|{{{http://www.xwiki.org/rel/comments}}}\|The representation of the list of comments associated to the current resource.
	42	\|{{{http://www.xwiki.org/rel/attachments}}}\|The representation of the list of attachments associated to the current resource.
	43	\|{{{http://www.xwiki.org/rel/objects}}}\|The representation of the list of objects associated to the current resource.
	44	\|{{{http://www.xwiki.org/rel/object}}}\|The representation for an object.
	45	\|{{{http://www.xwiki.org/rel/classes}}}\|The representation of the list of classes associated to the current resource.
	46	\|{{{http://www.xwiki.org/rel/history}}}\|The representation of the list of history information associated to the current resource.
	47	\|{{{http://www.xwiki.org/rel/class}}}\|The representation for a class.
	48	\|{{{http://www.xwiki.org/rel/property}}}\|The representation for a property.
	49	\|{{{http://www.xwiki.org/rel/properties}}}\|The representation of the list of properties associated to the current resource.
	50	\|{{{http://www.xwiki.org/rel/modifications}}}\|The representation of the list of modifications associated to the current resource.
	51	\|{{{http://www.xwiki.org/rel/children}}}\|The representation of the list of children associated to the current resource.
	52	\|{{{http://www.xwiki.org/rel/tags}}}\|The representation of the list of tags associated to the current resource.
	53	\|{{{http://www.xwiki.org/rel/tag}}}\|The representation of a tag.
	54	\|{{{http://www.xwiki.org/rel/search}}}\|The representation for a search resource.
9.2	55
8.3	56	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).
1.1	57
14.2	58	== The "HATEOAS" Graph ==
1.1	59
9.1	60	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.
9.2	61
1.1	62	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.
	63
14.2	64	= Interacting with the XWiki RESTful API =
8.2	65
9.5	66	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!
9.1	67	If you want to write more complex programs you might download an HTTP library for your favorite language (e.g., [[http://hc.apache.org/]]).
9.2	68
9.1	69	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.
9.2	70
5.1	71	If you use this approach (Apache HTTP Client + JAXB) you will find yourself writing some code like this:
1.1	72
10.6	73	{{code language="none"}}
1.1	74	HttpClient httpClient = new HttpClient();
	75	JAXBContext context = JAXBContext.newInstance("model.package");
	76	unmarshaller = context.createUnmarshaller();
	77
	78	GetMethod getMethod = new GetMethod("http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/WebHome");
	79	getMethod.addRequestHeader("Accept", "application/xml");
	80	httpClient.executeMethod(getMethod);
	81
	82	Page page = (Page) unmarshaller.unmarshal(getMethod.getResponseBodyAsStream());
9.1	83	{{/code}}
1.1	84
5.1	85	And you will have all the information about the Main.WebHome page in the Page object, without the need of handling XML directly.
9.2	86
9.1	87	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.
9.2	88
5.1	89	By using curl, the previous example would have been:
1.1	90
10.6	91	{{code language="none"}}
1.1	92	$ curl http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/WebHome
	93	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	94	<page xmlns="http://www.xwiki.org">
	95	<link rel="http://www.xwiki.org/rel/space" href="http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main"/>
	96	...
9.1	97	{{/code}}
1.1	98
14.2	99	== Authentication ==
1.1	100
5.1	101	The XWiki RESTful API supports two types of authentication:
1.1	102
9.1	103	* HTTP BASIC Auth: You provide your credentials using the Authorization HTTP header
	104	* 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.
9.2	105
5.1	106	If you don't provide any credentials the XWiki RESTful API will recognize you as a XWiki.Guest user.
9.2	107
5.1	108	So if you have, let's say a Main.PrivatePage, and you try to do:
1.1	109
10.6	110	{{code language="none"}}
1.1	111	$ curl -v http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/PrivatePage
	112	...
	113	< HTTP/1.1 401 Unauthorized
	114	...
9.1	115	{{/code}}
1.1	116
9.3	117	You will get an Unauthorized empty response.
9.2	118
1.1	119	On the contrary, by specifying Admin credentials you gain access to the actual page:
	120
10.6	121	{{code language="none"}}
1.1	122	$ curl -u Admin:admin http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/PrivatePage
	123	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	124	<page xmlns="http://www.xwiki.org">
	125	<link rel="http://www.xwiki.org/rel/space" href="http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main"/>
	126	...
	127	<content>Only admin can see this</content>
	128	</page>
9.1	129	{{/code}}
1.1	130
14.2	131	== Sending representations ==
1.1	132
	133	Many resources are modifiable, so you can send representations in order to change the state of those resources (e.g., pages).
9.1	134	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).
9.2	135
1.1	136	Resource update is usually done by using the PUT method, while resource creation is done via PUT or POST.
9.2	137
1.1	138	For example, in order to create a page you might do the following:
	139
10.6	140	{{code language="none"}}
1.1	141	$ curl -u Admin:admin -X PUT -d "@newpage.xml" -H "Content-Type: application/xml" http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/NewPage
	142	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	143	<page xmlns="http://www.xwiki.org">
	144	<link rel="http://www.xwiki.org/rel/space" href="http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main"/>
	145	...
	146	<version>1.1</version>
	147	<majorVersion>1</majorVersion>
	148	<minorVersion>1</minorVersion>
	149	<created>2009-03-21+01:00</created>
	150	<creator>XWiki.Admin</creator>
	151	<modified>2009-03-21+01:00</modified>
	152	<modifier>XWiki.Admin</modifier>
	153	<content>This is a new page</content>
	154	</page>
9.1	155	{{/code}}
1.1	156
	157	Where newpage.xml is an XML file containing
	158
10.6	159	{{code language="none"}}
1.1	160	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	161	<page xmlns="http://www.xwiki.org">
	162	<title>Hello world</title>
	163	<content>This is a new page</content>
	164	</page>
9.1	165	{{/code}}
1.1	166
	167	The page has been created and is accessible. Subsequent PUT requests to the page URI will modify its content.
	168
14.2	169	== Overcoming browser limitations ==
1.1	170
10.4	171	As said before, it could be useful to send information by using browser's XmlHttpRequest objects. However, 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 ##method## parameter in the URI query string.
9.2	172
10.4	173	In the previous example, if you send a POST request to the ##[[http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Main/pages/NewPage?method=PUT]]## it will be interpreted as if it were an actual PUT request.
1.1	174
	175	This overriding mechanism allows the interaction with the XWiki RESTful API by using any kind of browser.
	176
14.2	177	== PUT vs POST ==
1.1	178
10.4	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.
1.1	180
10.4	181	To be clearer, 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.
1.1	182
9.5	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.
1.1	184
14.2	185	= XWiki RESTful API Documentation =
8.4	186
9.5	187	In this section you will find the documentation of the whole XWiki RESTful API.
1.1	188
9.1	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]]
1.1	190
9.1	191	Resource URIs are specified using [[URI templates>>http://bitworking.org/projects/URI-Templates/spec/draft-gregorio-uritemplate-03.txt]]. Bracketed elements are formal parameters and should be instantiated to actual values in order to retrieve the associated resource.
1.1	192
14.2	193	== Root resources ==
1.1	194
16.3	195	By defaut all the resources of the RESTful API are rooted at the following URI: ##http:~//server:port/xwiki/rest/## (depending on where your XWiki is running)
16.1	196
14.2	197	=== / ===
9.1	198
	199	* HTTP Method: GET
	200	Media types:**
1.1	201	*** application/xml (XWiki element)
9.1	202	Description:** Retrieves the entry root description containing information about the server.
	203	Status codes:**
1.1	204	*** 200: If the request was successful.
	205
14.2	206	=== /wikis ===
9.1	207
	208	* HTTP Method: GET
	209	Media types:**
1.1	210	*** application/xml (Wikis element)
9.1	211	Description:** Retrieves the entry root description containing information about the server.
	212	Status codes:**
1.1	213	*** 200: If the request was successful.
	214
14.2	215	=== /wikis/{wikiName}/search?q~={keywords}~[~[&scope~={name,content,title,objects}...~]&number~=n~] ===
9.1	216
	217	* HTTP Method: GET
	218	Media types:**
1.1	219	*** application/xml (SearchResults element)
9.1	220	Description:** The list of pages and objects that contain the {keywords} in the specified {scope}s. Multiple scopes can be specified. Search results are relative to the whole {wikiName}
	221	Status codes:**
1.1	222	*** 200: If the request was successful.
	223
14.2	224	== Space resources ==
1.1	225
14.2	226	=== /wikis/{wikiName}/spaces[?start~=offset&number~=n] ===
9.1	227
	228	* HTTP Method: GET
	229	Media types:**
1.1	230	*** application/xml (Spaces element)
9.1	231	Description:** Retrieves the list of spaces available in the {wikiName} wiki.
	232	Status codes:**
1.1	233	*** 200: If the request was successful.
	234
14.2	235	=== /wikis/{wikiName}/spaces/{spaceName}/search?q~={keywords}~[~[&scope~={name,content,title,objects}...~]&number~=n~] ===
9.1	236
	237	* HTTP Method: GET
	238	Media types:**
1.1	239	*** application/xml (Search results element)
9.1	240	Description:** The list of pages and objects that contain the {keywords} in the specified {scope}s. Multiple scopes can be specified. Search results are relative to space {spaceName}
	241	Status codes:**
1.1	242	*** 200: If the request was successful.
	243	*** 401: If the user is not authorized.
	244
14.2	245	== Page resources ==
1.1	246
14.2	247	=== /wikis/{wikiName}/spaces/{spaceName}/pages[?start~=offset&number~=n] ===
9.1	248
	249	* HTTP Method: GET
	250	Media types:**
1.1	251	*** application/xml (Pages element)
9.1	252	Description:** The list of pages in the space {spaceName}
	253	Status codes:**
1.1	254	*** 200: If the request was successful
	255	*** 401: If the user is not authorized.
	256
14.2	257	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName} ===
9.1	258
	259	* HTTP Method: GET
	260	Media types:**
1.1	261	*** application/xml (Page element)
9.1	262	Description:**
	263	Status codes:**
1.1	264	*** 200: If the request was successful.
	265	*** 401: If the user is not authorized.
9.1	266
	267	\\
	268
	269	* HTTP Method: PUT
	270	Accepted Media types:**
1.1	271	*** application/xml (Page element)
	272	*** text/plain (Only page content)
	273	*** application/x-www-form-urlencoded (allowed field names: title, parent, content)
9.1	274	Media types:**
1.1	275	*** application/xml (Page element)
9.1	276	Description:** Create or updates a page.
	277	Status codes:**
1.1	278	*** 201: If the page was created.
	279	*** 202: If the page was updated.
	280	*** 304: If the page was not modified.
	281	*** 401: If the user is not authorized.
9.1	282
	283	\\
	284
	285	* HTTP Method: DELETE
	286	Media types:**
1.1	287	*** application/xml (Page element)
9.1	288	Description:** Delete the page.
	289	Status codes:**
1.1	290	*** 204: If the request was successful.
	291	*** 401: If the user is not authorized.
	292
14.2	293	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history[?start~=offset&number~=n] ===
9.1	294
	295	* HTTP Method: GET
	296	Media types:**
1.1	297	*** application/xml (History element)
9.1	298	Description:** The list of all the versions of the given page.
	299	Status codes:**
1.1	300	*** 200: If the request was successful.
	301	*** 401: If the user is not authorized.
	302
14.2	303	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history/{version} ===
9.1	304
	305	* HTTP Method: GET
	306	Media types:**
1.1	307	*** application/xml (Page element)
9.1	308	Description:** The page at version {version}
	309	Status codes:**
1.1	310	*** 200: If the request was successful.
	311	*** 401: If the user is not authorized.
	312
10.1	313	==== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/translations[?start~=offset&number~=n] ====
9.1	314
	315	* HTTP Method: GET
	316	Media types:**
1.1	317	*** application/xml (Translations element)
9.1	318	Description:** The list of available translation for the page
	319	Status codes:**
1.1	320	*** 200: If the request was successful.
	321	*** 401: If the user is not authorized.
	322
14.2	323	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/translations/{language} ===
9.1	324
	325	* HTTP Method: GET
	326	Media types:**
1.1	327	*** application/xml (Page element)
9.1	328	Description:** The page at in the given {language}.
	329	Status codes:**
1.1	330	*** 200: If the request was successful.
	331	*** 401: If the user is not authorized.
9.1	332
	333	\\
	334
	335	* HTTP Method: PUT
	336	Accepted Media types:**
1.1	337	*** application/xml (Page element)
	338	*** text/plain (Only page content)
	339	*** application/x-www-form-urlencoded (allowed field names: title, parent, content)
9.1	340	Media types:**
1.1	341	*** application/xml (Page element)
9.1	342	Description:** Create or updates a page translation.
	343	Status codes:**
1.1	344	*** 201: If the page was created.
	345	*** 202: If the page was updated.
	346	*** 304: If the page was not modified.
	347	*** 401: If the user is not authorized.
9.1	348
	349	\\
	350
	351	* HTTP Method: DELETE
	352	Media types:**
1.1	353	*** application/xml (Page element)
9.1	354	Description:** Delete the page translation.
	355	Status codes:**
1.1	356	*** 204: If the request was successful.
	357	*** 401: If the user is not authorized.
	358
14.2	359	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/translations/{language}/history ===
9.1	360
	361	* HTTP Method: GET
	362	Media types:**
1.1	363	*** application/xml (History element)
9.1	364	Description:** The list of all the available revisions of the page in a given {language}.
	365	Status codes:**
1.1	366	*** 200: If the request was successful.
	367	*** 401: If the user is not authorized.
	368
14.2	369	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/translations/{lang}/history/{version} ===
9.1	370
	371	* HTTP Method: GET
	372	Media types:**
1.1	373	*** application/xml (Page element)
9.1	374	Description:** A page at a given {version} in a given {language}.
	375	Status codes:**
1.1	376	*** 200: If the request was successful.
	377	*** 401: If the user is not authorized.
	378
14.2	379	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/children ===
9.1	380
	381	* HTTP Method: GET
	382	Media types:**
1.1	383	*** application/xml (Pages element)
9.1	384	Description:** The list of the children of a given page.
	385	Status codes:**
1.1	386	*** 200: If the request was successful.
	387	*** 401: If the user is not authorized.
	388
14.2	389	== Tag resources ==
1.1	390
14.2	391	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/tags ===
9.1	392
	393	* HTTP Method: GET
	394	Media types:**
1.1	395	*** application/xml (Tags element)
9.1	396	Description:** List page tags.
	397	Status codes:**
1.1	398	*** 200: If the request was successful.
	399	*** 401: If the user is not authorized.
9.1	400
	401	\\
	402
	403	* HTTP Method: PUT
	404	Accepted Media types:**
1.1	405	*** application/xml (Tag element)
	406	*** text/plain
	407	*** application/x-www-form-urlencoded (allowed field names: tag)
9.1	408	Media types:**
1.1	409	*** application/xml (Tags element)
9.1	410	Description:** Add a tag to the page.
	411	Status codes:**
1.1	412	*** 202: If the request was successful.
	413	*** 401: If the user is not authorized.
	414
14.2	415	=== /wikis/{wikiName}/tags ===
9.1	416
	417	* HTTP Method: GET
	418	Media types:**
1.1	419	*** application/xml (Tags element)
9.1	420	Description:** The list of all available tags
	421	Status codes:**
1.1	422	*** 200: If the request was successful.
	423	*** 401: If the user is not authorized.
	424
14.2	425	=== /wikis/{wikiName}/tags/{tag1}[,{tag2},{tag3}...][?start~=offset&number~=n] ===
9.1	426
	427	* HTTP Method: GET
	428	Media types:**
1.1	429	*** application/xml (Pages element)
9.1	430	Description:** The list of pages having the specified tags.
	431	Status codes:**
1.1	432	*** 200: If the request was successful.
	433	*** 401: If the user is not authorized.
	434
14.2	435	== Comments resources ==
1.1	436
14.2	437	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/comments[?start~=offset&number~=n] ===
9.1	438
	439	* HTTP Method: GET
	440	Media types:**
1.1	441	*** application/xml (Comments element)
9.1	442	Description:** The list of comments on a given page.
	443	Status codes:**
1.1	444	*** 200: If the request was successful.
	445	*** 401: If the user is not authorized.
9.1	446
	447	\\
	448
	449	* HTTP Method: POST
	450	Accepted Media types:**
1.1	451	*** application/xml (Comment element)
	452	*** text/plain
	453	*** application/x-www-form-urlencoded (allowed field names: text)
9.1	454	Media types:**
1.1	455	*** application/xml (Comment element)
9.1	456	Description:** Create a comment on the given page.
	457	Status codes:**
1.1	458	*** 201: If the comment was created. (The Location header will contain the URI where the comment has been created.)
	459	*** 401: If the user is not authorized.
	460
14.2	461	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/comments/{commentId} ===
9.1	462
	463	* HTTP Method: GET
	464	Media types:**
1.1	465	*** application/xml (Comment element)
9.1	466	Description:** A specific comment on a page
	467	Status codes:**
1.1	468	*** 200: If the request was successful.
	469	*** 401: If the user is not authorized.
	470
14.2	471	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history/{version}/comments ===
9.1	472
	473	* HTTP Method: GET
	474	Media types:**
1.1	475	*** application/xml (Comments element)
9.1	476	Description:** The list of comments at a specific page {version}.
	477	Status codes:**
1.1	478	*** 200: If the request was successful.
	479	*** 401: If the user is not authorized.
	480
14.2	481	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history/{version}/comments/{commentId} ===
9.1	482
	483	* HTTP Method: GET
	484	Media types:**
1.1	485	*** application/xml (Comment element)
9.1	486	Description:** A comment at a specific page {version}.
	487	Status codes:**
1.1	488	*** 200: If the request was successful.
	489	*** 401: If the user is not authorized.
	490
14.2	491	== Attachments resources ==
1.1	492
14.2	493	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/attachments[?start~=offset&number~=n] ===
9.1	494
	495	* HTTP Method: GET
	496	Media types:**
1.1	497	*** application/xml (Attachments element)
9.1	498	Description:** The list of attachments of a given page.
	499	Status codes:**
1.1	500	*** 200: If the request was successful.
	501	*** 401: If the user is not authorized.
	502
14.2	503	=== /wikis/{wikiName}/wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/attachments/{attachmentName} ===
9.1	504
	505	* HTTP Method: GET
	506	Media types:**
1.1	507	*** The same of the attachment media type.
9.1	508	Description:** The attachment identified by {attachmentName} on a given page.
	509	Status codes:**
1.1	510	*** 200: If the request was successful.
	511	*** 401: If the user is not authorized.
9.1	512
	513	\\
	514
	515	* HTTP Method: PUT
	516	Accepted media types:**
	517	* /**
	518	Media types:**
1.1	519	*** application/xml (AttachmentSummary element)
9.1	520	Description:** Create an attachment identified by {attachmentName} on a given page.
	521	Status codes:**
1.1	522	*** 201: If the attachment was created.
	523	*** 202: If the attachment was updated.
	524	*** 401: If the user is not authorized.
9.1	525
	526	\\
	527
	528	* HTTP Method: DELETE
	529	Media types:**
	530	Description:** Delete the attachment identified by {attachmentName} on a given page.
	531	Status codes:**
1.1	532	*** 204: If the attachment was deleted.
	533	*** 401: If the user is not authorized.
	534
14.2	535	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history/{version}/attachments[?start~=offset&number~=n] ===
9.1	536
	537	* HTTP Method: GET
	538	Media types:**
1.1	539	*** application/xml (Attachments element)
9.1	540	Description:** The list of attachments at a given page {version}.
	541	Status codes:**
1.1	542	*** 200: If the request was successful.
	543	*** 401: If the user is not authorized.
	544
14.2	545	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history/{version}/attachments/{attachmentName} ===
9.1	546
	547	* HTTP Method: GET
	548	Media types:**
1.1	549	*** The same of the attachment media type.
9.1	550	Description:** The attachment identified by {attachmentName} on a given page {version}.
	551	Status codes:**
1.1	552	*** 200: If the request was successful.
	553	*** 401: If the user is not authorized.
	554
14.2	555	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/attachments/{attachmentName}/history ===
9.1	556
	557	* HTTP Method: GET
	558	Media types:**
1.1	559	*** application/xml (??? element)
9.1	560	Description:** The list of available version for the {attachmentName}
	561	Status codes:**
1.1	562	*** 200: If the request was successful.
	563	*** 401: If the user is not authorized.
	564
14.2	565	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/attachments/{attachmentName}/history/{version} ===
9.1	566
	567	* HTTP Method: GET
	568	Media types:**
1.1	569	*** The same of the attachment media type.
9.1	570	Description:** The {attachmentName} at a given {version}
	571	Status codes:**
1.1	572	*** 200: If the request was successful.
	573	*** 401: If the user is not authorized.
	574
14.2	575	== Object resources ==
1.1	576
14.2	577	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/objects[?start~=offset&number~=n] ===
9.1	578
	579	* HTTP Method: GET
	580	Media types:**
1.1	581	*** application/xml (Objects element)
9.1	582	Description:** The list of objects associated to a page.
	583	Status codes:**
1.1	584	*** 200: If the request was successful.
	585	*** 401: If the user is not authorized.
9.1	586
	587	\\
	588
	589	* HTTP Method: POST
	590	Accepted media types:**
1.1	591	*** application/xml (Object element)
	592	*** application/x-www-formurlencoded (a set of property#name=value pairs representing properties and a field className)
9.1	593	Media types:**
	594	*** application/xml (Object element)
	595	Description:** Create a new object.
	596	Status codes:**
1.1	597	*** 201: If the object was created (The Location header will contain the URI associated to the newly created object).
	598	*** 401: If the user is not authorized.
	599
14.2	600	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/objects/{className}[?start~=offset&number~=n] ===
9.1	601
	602	* HTTP Method: GET
	603	Media types:**
1.1	604	*** application/xml (Objects element)
9.1	605	Description:** The list of objects of a given {className} associated to a page.
	606	Status codes:**
1.1	607	*** 200: If the request was successful.
	608	*** 401: If the user is not authorized.
	609
14.2	610	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/objects/{className}/{objectNumber} ===
9.1	611
	612	* HTTP Method: GET
	613	Media types:**
1.1	614	*** application/xml (Object element)
9.1	615	Description:** The object of type {className} identified by {objectNumber} associated to the given page.
	616	Status codes:**
1.1	617	*** 200: If the request was successful.
	618	*** 401: If the user is not authorized.
9.1	619
	620	\\
	621
	622	* HTTP Method: PUT
	623	Accepted media types:**
1.1	624	*** application/xml (Object element)
	625	*** application/x-www-formurlencoded (a set of property#name=value pairs representing properties)
9.1	626	Media types:**
	627	*** application/xml (Object element)
	628	Description:** Modify the object properties.
	629	Status codes:**
1.1	630	*** 202: If the object was updated.
	631	*** 401: If the user is not authorized.
9.1	632
	633	\\
	634
	635	* HTTP Method: DELETE
	636	Media types:**
	637	Description:** Delete the object.
	638	Status codes:**
1.1	639	*** 204: If the object was deleted.
	640	*** 401: If the user is not authorized.
	641
14.2	642	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/objects/{className}/{objectNumber}/properties ===
9.1	643
	644	* HTTP Method: GET
	645	Media types:**
1.1	646	*** application/xml (Properties element)
9.1	647	Description:** The properties of the object of type {className} identified by {objectNumber} associated to the given page.
	648	Status codes:**
1.1	649	*** 200: If the request was successful.
	650	*** 401: If the user is not authorized.
	651
14.2	652	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/objects/{className}/{objectNumber}/properties/{propertyName} ===
9.1	653
	654	* HTTP Method: GET
	655	Media types:**
1.1	656	*** application/xml (Properties element)
9.1	657	Description:** The property {propertyname} of the object of type {className} identified by {objectNumber} associated to the given page.
	658	Status codes:**
1.1	659	*** 200: If the request was successful.
	660	*** 401: If the user is not authorized.
9.1	661
	662	\\
	663
	664	* HTTP Method: PUT
	665	Accepted media types:**
1.1	666	*** application/xml (Property element)
	667	*** text/plain
	668	*** application/x-www-formurlencoded (a field property#name=value pairs representing a property)
9.1	669	Media types:**
	670	*** application/xml (Property element)
	671	Description:** Modify the object properties.
	672	Status codes:**
1.1	673	*** 202: If the object was updated.
	674	*** 401: If the user is not authorized.
	675
14.2	676	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history/{version}/objects[?start~=offset&number~=n] ===
9.1	677
	678	* HTTP Method: GET
	679	Media types:**
1.1	680	*** application/xml (Objects element)
9.1	681	Description:** The list of objects associated to a page at a given {version}.
	682	Status codes:**
1.1	683	*** 200: If the request was successful.
	684	*** 401: If the user is not authorized.
	685
14.2	686	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history/{version}/objects/{className}/{objectNumber} ===
9.1	687
	688	* HTTP Method: GET
	689	Media types:**
1.1	690	*** application/xml (Object element)
9.1	691	Description:** The object of type {className} identified by {objectNumber} associated to the given page at a given {version}.
	692	Status codes:**
1.1	693	*** 200: If the request was successful.
	694	*** 401: If the user is not authorized.
	695
14.2	696	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history/{version}/objects/{className}/{objectNumber}/properties ===
9.1	697
	698	* HTTP Method: GET
	699	Media types:**
1.1	700	*** application/xml (Properties element)
9.1	701	Description:** The properties of the object of type {className} identified by {objectNumber} associated to the given page at a given {version}.
	702	Status codes:**
1.1	703	*** 200: If the request was successful.
	704	*** 401: If the user is not authorized.
	705
14.2	706	=== /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}/history/{version}/objects/{className}/{objectNumber}/properties/{propertyName} ===
9.1	707
	708	* HTTP Method: GET
	709	Media types:**
1.1	710	*** application/xml (Properties element)
9.1	711	Description:** The property {propertyname} of the object of type {className} identified by {objectNumber} associated to the given page at a given {version}.
	712	Status codes:**
1.1	713	*** 200: If the request was successful.
	714	*** 401: If the user is not authorized.
	715
14.2	716	=== /wikis/{wikiName}/class/{className}/objects ===
9.1	717
	718	* HTTP Method: GET
	719	Media types:**
1.1	720	*** application/xml (Objects element)
9.1	721	Description:** The list of all the objects of a given {className}.
	722	Status codes:**
1.1	723	*** 200: If the request was successful.
	724	*** 401: If the user is not authorized.
	725
14.2	726	== Class resources ==
1.1	727
14.2	728	=== /wikis/{wikiName}/classes[?start~=offset&number~=n] ===
9.1	729
	730	* HTTP Method: GET
	731	Media types:**
1.1	732	*** application/xml (Classes element)
9.1	733	Description:** The list of all the classes defined in the wiki {wikiName}
	734	Status codes:**
1.1	735	*** 200: If the request was successful.
	736	*** 401: If the user is not authorized.
	737
14.2	738	=== /wikis/{wikiName}/classes/{className} ===
9.1	739
	740	* HTTP Method: GET
	741	Media types:**
1.1	742	*** application/xml (Class element)
9.1	743	Description:** The {className} definition
	744	Status codes:**
1.1	745	*** 200: If the request was successful.
	746	*** 401: If the user is not authorized.
	747
14.2	748	=== /wikis/{wikiName}/classes/{className}/properties ===
9.1	749
	750	* HTTP Method: GET
	751	Media types:**
1.1	752	*** application/xml (Properties element)
9.1	753	Description:** The properties of the class {className}.
	754	Status codes:**
1.1	755	*** 200: If the request was successful.
	756	*** 401: If the user is not authorized.
	757
14.2	758	=== /wikis/{wikiName}/classes/{className}/properties/{property} ===
9.1	759
	760	* HTTP Method: GET
	761	Media types:**
1.1	762	*** application/xml (Property element)
9.1	763	Description:** The property {property} of the class {className}.
	764	Status codes:**
1.1	765	*** 200: If the request was successful.
	766	*** 401: If the user is not authorized.
	767
14.2	768	== Other resources ==
1.1	769
14.2	770	=== /wikis/{wikiName}/modifications[?start~=offset&number~=n&timestamp~=t] ===
9.1	771
	772	* HTTP Method: GET
	773	Media types:**
1.1	774	*** application/xml (Modifications element)
9.1	775	Description:** The list of the latest modification made to the wiki {wikiName} starting from time t (t is expressed in milliseconds from 1970 of the starting date)
	776	Status codes:**
1.1	777	*** 200: If the request was successful.
	778	*** 401: If the user is not authorized.

Wiki source code of The XWiki RESTful API

Quick Links

Navigation

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected