Project

General

Profile

Rest WikiPages » History » Version 6

Jens Krämer, 2017-02-28 03:34
since 3.3 wiki_controller supports the nested uploads element which is necessary for using the XML version of the API (single root node needed)

1 1 Jean-Philippe Lang
h1. Wiki Pages
2
3
{{>toc}}
4
5
h2. Getting the pages list of a wiki
6
7
<pre>
8
GET /projects/foo/wiki/index.xml
9
</pre>
10
11
Returns the list of all pages in a project wiki.
12
13
+Response+:
14
15
<pre>
16
<?xml version="1.0"?>
17
<wiki_pages type="array">
18
  <wiki_page>
19
    <title>UsersGuide</title>
20
    <version>2</version>
21
    <created_on>2008-03-09T12:07:08Z</created_on>
22
    <updated_on>2008-03-09T23:41:33+01:00</updated_on>
23
  </wiki_page>
24
  ...
25
</wiki_pages>
26
</pre>
27
28
h2. Getting a wiki page
29
30
<pre>
31
GET /projects/foo/wiki/UsersGuide.xml
32
</pre>
33
34
Returns the details of a wiki page.
35
36
+Includable+:
37
* attachments
38
39
+Response+:
40
41
<pre>
42
<?xml version="1.0"?>
43
<wiki_page>
44
  <title>UsersGuide</title>
45
  <parent title="Installation_Guide"/>
46
  <text>h1. Users Guide
47
  ...
48
  ...</text>
49
  <version>22</version>
50
  <author id="11" name="John Smith"/>
51
  <comments>Typo</comments>
52
  <created_on>2009-05-18T20:11:52Z</created_on>
53
  <updated_on>2012-10-02T11:38:18Z</updated_on>
54
</wiki_page>
55
</pre>
56
57 3 Jean-Philippe Lang
h2. Getting an old version of a wiki page
58
59
<pre>
60
GET /projects/foo/wiki/UsersGuide/23.xml
61
</pre>
62
63
Returns the details of an old version of a wiki page.
64
65
+Includable+:
66
* attachments
67
68
+Response+:
69
70
Same as above.
71
72 1 Jean-Philippe Lang
h2. Creating or updating a wiki page
73
74
<pre>
75
PUT /projects/foo/wiki/UsersGuide.xml
76
<?xml version="1.0"?>
77
<wiki_page>
78
  <text>Example</text>
79
  <comments>Typo</comments>
80 4 Kevin Saliou
</wiki_page>
81 1 Jean-Philippe Lang
</pre>
82
83
Creates or updates a wiki page.
84
85
When updating an existing page, you can include a @version@ attribute to make sure that the page is a specific version when you try to update it (eg. you don't want to overwrite an update that would have been done after you retrieved the page). Example:
86
87
<pre>
88
PUT /projects/foo/wiki/UsersGuide.xml
89
<?xml version="1.0"?>
90
<wiki_page>
91
  <text>Example</text>
92
  <comments>Typo</comments>
93
  <version>18</version>
94 4 Kevin Saliou
</wiki_page>
95 1 Jean-Philippe Lang
</pre>
96
97
This would update the page if its current version is 18, otherwise a @409 Conflict@ error is returned.
98
99 5 Máté Katona
h3. Attaching files
100
101
+JSON example+
102
103
First, upload your file(s):
104
105
<pre>
106
POST /uploads.json
107
Content-Type: application/octet-stream
108
...
109
(request body is the file content)
110
111
# 201 response
112
{"upload":{"token":"7167.ed1ccdb093229ca1bd0b043618d88743"}}
113
</pre>
114
115
If you want to attach more than one file, upload them one by one, and save all the tokens.
116
Then create/update the wiki page using the attachments token (with one or more files provided as an array of objects):
117
118
<pre>
119
PUT /projects/project_name/wiki/wiki_name.json
120 1 Jean-Philippe Lang
{
121
    "wiki_page": {
122 6 Jens Krämer
        "text": "This is a wiki page with images (like this: !img.png!), and other files.",
123
        "uploads": [
124
            {"token": "7167.ed1ccdb093229ca1bd0b043618d88743", "filename": "img.bmp", "content-type": "image/png"},
125
            {"token": "7168.d595398bbb104ed3bba0eed666785cc6", "filename": "document.pdf", "content-type": "application/pdf"}
126
        ]
127
    }
128 5 Máté Katona
}
129
</pre>
130
131
+Note:+
132
133
When creating or updating wiki pages, the text field must be provided, otherwise you will get a @422 Unprocessable Entity@ error saying: "Text field can't be blank".
134
If you do not wish to change the text, you can keep it by first getting the wiki page as described above, and provide the current text in the update.
135
136
137
138 1 Jean-Philippe Lang
+Response+:
139
* @200 OK@: page was updated
140
* @201 Created@: page was created
141
* @409 Conflict@: occurs when trying to update a stale page (see above)
142
* @422 Unprocessable Entity@: page was not saved due to validation failures (response body contains the error messages)
143 2 Jean-Philippe Lang
144
h2. Deleting a wiki page
145
146
<pre>
147
DELETE /projects/foo/wiki/UsersGuide.xml
148
</pre>
149
150
Deletes a wiki page, its attachments and its history. If the deleted page is a parent page, its child pages are not deleted but changed as root pages.
151
152
+Response+:
153
* @200 OK@: page was deleted