Mercurial > kallithea
annotate docs/api/api.rst @ 1839:9da24750f563 beta
docs update
author | Marcin Kuzminski <marcin@python-works.com> |
---|---|
date | Fri, 06 Jan 2012 21:50:52 +0200 |
parents | 320dec24fb9a |
children | 0771f0f5ab28 |
rev | line source |
---|---|
1446 | 1 .. _api: |
2 | |
3 | |
4 API | |
5 === | |
6 | |
7 | |
8 Starting from RhodeCode version 1.2 a simple API was implemented. | |
1500 | 9 There's a single schema for calling all api methods. API is implemented |
1592 | 10 with JSON protocol both ways. An url to send API request in RhodeCode is |
1500 | 11 <your_server>/_admin/api |
1446 | 12 |
1839 | 13 API ACCESS FOR WEB VIEWS |
14 ++++++++++++++++++++++++ | |
1446 | 15 |
1812
320dec24fb9a
Added instruction on enabling the API access to web views
Marcin Kuzminski <marcin@python-works.com>
parents:
1810
diff
changeset
|
16 API access can also be turned on for each view decorated with `@LoginRequired` |
320dec24fb9a
Added instruction on enabling the API access to web views
Marcin Kuzminski <marcin@python-works.com>
parents:
1810
diff
changeset
|
17 decorator. To enable API access simple change standard login decorator into |
320dec24fb9a
Added instruction on enabling the API access to web views
Marcin Kuzminski <marcin@python-works.com>
parents:
1810
diff
changeset
|
18 `@LoginRequired(api_access=True)`. After such a change view can be accessed |
320dec24fb9a
Added instruction on enabling the API access to web views
Marcin Kuzminski <marcin@python-works.com>
parents:
1810
diff
changeset
|
19 by adding a GET parameter to url `?api_key=<api_key>`. By default it's only |
320dec24fb9a
Added instruction on enabling the API access to web views
Marcin Kuzminski <marcin@python-works.com>
parents:
1810
diff
changeset
|
20 enabled on RSS/ATOM feed views. |
320dec24fb9a
Added instruction on enabling the API access to web views
Marcin Kuzminski <marcin@python-works.com>
parents:
1810
diff
changeset
|
21 |
320dec24fb9a
Added instruction on enabling the API access to web views
Marcin Kuzminski <marcin@python-works.com>
parents:
1810
diff
changeset
|
22 |
1839 | 23 API ACCESS |
24 ++++++++++ | |
25 | |
1708
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1592
diff
changeset
|
26 All clients are required to send JSON-RPC spec JSON data:: |
1446 | 27 |
1708
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1592
diff
changeset
|
28 { |
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1592
diff
changeset
|
29 "id:<id>, |
1446 | 30 "api_key":"<api_key>", |
31 "method":"<method_name>", | |
32 "args":{"<arg_key>":"<arg_val>"} | |
33 } | |
34 | |
1500 | 35 Example call for autopulling remotes repos using curl:: |
1708
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1592
diff
changeset
|
36 curl https://server.com/_admin/api -X POST -H 'content-type:text/plain' --data-binary '{"id":1,"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}' |
1500 | 37 |
1592 | 38 Simply provide |
1708
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1592
diff
changeset
|
39 - *id* A value of any type, which is used to match the response with the request that it is replying to. |
1500 | 40 - *api_key* for access and permission validation. |
41 - *method* is name of method to call | |
42 - *args* is an key:value list of arguments to pass to method | |
1592 | 43 |
1446 | 44 .. note:: |
1592 | 45 |
46 api_key can be found in your user account page | |
47 | |
48 | |
1708
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1592
diff
changeset
|
49 RhodeCode API will return always a JSON-RPC response:: |
1592 | 50 |
1708
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1592
diff
changeset
|
51 { |
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1592
diff
changeset
|
52 "id":<id>, |
1592 | 53 "result": "<result>", |
1446 | 54 "error": null |
55 } | |
56 | |
57 All responses from API will be `HTTP/1.0 200 OK`, if there's an error while | |
1592 | 58 calling api *error* key from response will contain failure description |
1446 | 59 and result will be null. |
60 | |
61 API METHODS | |
62 +++++++++++ | |
63 | |
1592 | 64 |
1446 | 65 pull |
66 ---- | |
67 | |
1592 | 68 Pulls given repo from remote location. Can be used to automatically keep |
69 remote repos up to date. This command can be executed only using api_key | |
1500 | 70 belonging to user with admin rights |
71 | |
72 INPUT:: | |
73 | |
1592 | 74 api_key : "<api_key>" |
75 method : "pull" | |
76 args : { | |
77 "repo" : "<repo_name>" | |
78 } | |
79 | |
80 OUTPUT:: | |
81 | |
82 result : "Pulled from <repo_name>" | |
83 error : null | |
84 | |
85 | |
86 get_users | |
87 --------- | |
88 | |
89 Lists all existing users. This command can be executed only using api_key | |
90 belonging to user with admin rights. | |
91 | |
92 INPUT:: | |
93 | |
94 api_key : "<api_key>" | |
95 method : "get_users" | |
96 args : { } | |
97 | |
98 OUTPUT:: | |
99 | |
100 result: [ | |
101 { | |
102 "id" : "<id>", | |
103 "username" : "<username>", | |
104 "firstname": "<firstname>", | |
105 "lastname" : "<lastname>", | |
106 "email" : "<email>", | |
107 "active" : "<bool>", | |
108 "admin" : "<bool>", | |
109 "ldap" : "<ldap_dn>" | |
110 }, | |
111 … | |
112 ] | |
113 error: null | |
114 | |
115 create_user | |
116 ----------- | |
117 | |
118 Creates new user in RhodeCode. This command can be executed only using api_key | |
119 belonging to user with admin rights. | |
120 | |
121 INPUT:: | |
122 | |
123 api_key : "<api_key>" | |
124 method : "create_user" | |
125 args : { | |
126 "username" : "<username>", | |
127 "password" : "<password>", | |
128 "firstname" : "<firstname>", | |
129 "lastname" : "<lastname>", | |
130 "email" : "<useremail>" | |
131 "active" : "<bool> = True", | |
132 "admin" : "<bool> = False", | |
133 "ldap_dn" : "<ldap_dn> = None" | |
134 } | |
1500 | 135 |
136 OUTPUT:: | |
137 | |
1592 | 138 result: { |
139 "msg" : "created new user <username>" | |
140 } | |
141 error: null | |
142 | |
143 get_users_groups | |
144 ---------------- | |
145 | |
146 Lists all existing users groups. This command can be executed only using api_key | |
147 belonging to user with admin rights. | |
148 | |
149 INPUT:: | |
150 | |
151 api_key : "<api_key>" | |
152 method : "get_users_groups" | |
153 args : { } | |
154 | |
155 OUTPUT:: | |
156 | |
157 result : [ | |
158 { | |
159 "id" : "<id>", | |
160 "name" : "<name>", | |
161 "active": "<bool>", | |
162 "members" : [ | |
163 { | |
164 "id" : "<userid>", | |
165 "username" : "<username>", | |
166 "firstname": "<firstname>", | |
167 "lastname" : "<lastname>", | |
168 "email" : "<email>", | |
169 "active" : "<bool>", | |
170 "admin" : "<bool>", | |
171 "ldap" : "<ldap_dn>" | |
172 }, | |
173 … | |
174 ] | |
175 } | |
176 ] | |
177 error : null | |
178 | |
179 get_users_group | |
180 --------------- | |
181 | |
182 Gets an existing users group. This command can be executed only using api_key | |
183 belonging to user with admin rights. | |
184 | |
185 INPUT:: | |
186 | |
187 api_key : "<api_key>" | |
188 method : "get_users_group" | |
189 args : { | |
190 "group_name" : "<name>" | |
191 } | |
192 | |
193 OUTPUT:: | |
194 | |
195 result : None if group not exist | |
196 { | |
197 "id" : "<id>", | |
198 "name" : "<name>", | |
199 "active": "<bool>", | |
200 "members" : [ | |
201 { "id" : "<userid>", | |
202 "username" : "<username>", | |
203 "firstname": "<firstname>", | |
204 "lastname" : "<lastname>", | |
205 "email" : "<email>", | |
206 "active" : "<bool>", | |
207 "admin" : "<bool>", | |
208 "ldap" : "<ldap_dn>" | |
209 }, | |
210 … | |
211 ] | |
212 } | |
213 error : null | |
214 | |
1500 | 215 create_users_group |
216 ------------------ | |
217 | |
1592 | 218 Creates new users group. This command can be executed only using api_key |
1500 | 219 belonging to user with admin rights |
220 | |
221 INPUT:: | |
222 | |
1592 | 223 api_key : "<api_key>" |
224 method : "create_users_group" | |
225 args: { | |
226 "name": "<name>", | |
227 "active":"<bool> = True" | |
228 } | |
229 | |
230 OUTPUT:: | |
231 | |
232 result: { | |
233 "id": "<newusersgroupid>", | |
234 "msg": "created new users group <name>" | |
235 } | |
236 error: null | |
237 | |
1793
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
238 add_user_to_users_group |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
239 ----------------------- |
1592 | 240 |
241 Adds a user to a users group. This command can be executed only using api_key | |
242 belonging to user with admin rights | |
243 | |
244 INPUT:: | |
245 | |
246 api_key : "<api_key>" | |
247 method : "add_user_users_group" | |
248 args: { | |
249 "group_name" : "<groupname>", | |
1810
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
250 "username" : "<username>" |
1592 | 251 } |
252 | |
253 OUTPUT:: | |
254 | |
255 result: { | |
256 "id": "<newusersgroupmemberid>", | |
257 "msg": "created new users group member" | |
258 } | |
259 error: null | |
260 | |
261 get_repos | |
262 --------- | |
263 | |
264 Lists all existing repositories. This command can be executed only using api_key | |
265 belonging to user with admin rights | |
266 | |
267 INPUT:: | |
268 | |
269 api_key : "<api_key>" | |
270 method : "get_repos" | |
271 args: { } | |
1500 | 272 |
273 OUTPUT:: | |
274 | |
1592 | 275 result: [ |
276 { | |
277 "id" : "<id>", | |
278 "name" : "<name>" | |
279 "type" : "<type>", | |
280 "description" : "<description>" | |
281 }, | |
282 … | |
283 ] | |
284 error: null | |
285 | |
286 get_repo | |
287 -------- | |
288 | |
289 Gets an existing repository. This command can be executed only using api_key | |
290 belonging to user with admin rights | |
291 | |
292 INPUT:: | |
293 | |
294 api_key : "<api_key>" | |
295 method : "get_repo" | |
296 args: { | |
297 "name" : "<name>" | |
298 } | |
299 | |
300 OUTPUT:: | |
301 | |
302 result: None if repository not exist | |
303 { | |
304 "id" : "<id>", | |
305 "name" : "<name>" | |
306 "type" : "<type>", | |
307 "description" : "<description>", | |
308 "members" : [ | |
309 { "id" : "<userid>", | |
310 "username" : "<username>", | |
311 "firstname": "<firstname>", | |
312 "lastname" : "<lastname>", | |
313 "email" : "<email>", | |
314 "active" : "<bool>", | |
315 "admin" : "<bool>", | |
316 "ldap" : "<ldap_dn>", | |
1793
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
317 "permission" : "repository.(read|write|admin)" |
1592 | 318 }, |
319 … | |
320 { | |
321 "id" : "<usersgroupid>", | |
322 "name" : "<usersgroupname>", | |
323 "active": "<bool>", | |
1793
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
324 "permission" : "repository.(read|write|admin)" |
1592 | 325 }, |
326 … | |
327 ] | |
328 } | |
329 error: null | |
330 | |
1810
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
331 get_repo_nodes |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
332 -------------- |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
333 |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
334 returns a list of nodes and it's children in a flat list for a given path |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
335 at given revision. It's possible to specify ret_type to show only files or |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
336 dirs. This command can be executed only using api_key belonging to user |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
337 with admin rights |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
338 |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
339 INPUT:: |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
340 |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
341 api_key : "<api_key>" |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
342 method : "get_repo_nodes" |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
343 args: { |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
344 "repo_name" : "<name>", |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
345 "revision" : "<revision>", |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
346 "root_path" : "<root_path>", |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
347 "ret_type" : "<ret_type>" = 'all' |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
348 } |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
349 |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
350 OUTPUT:: |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
351 |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
352 result: [ |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
353 { |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
354 "name" : "<name>" |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
355 "type" : "<type>", |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
356 }, |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
357 … |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
358 ] |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
359 error: null |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
360 |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
361 |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
362 |
1592 | 363 create_repo |
364 ----------- | |
365 | |
366 Creates a repository. This command can be executed only using api_key | |
367 belonging to user with admin rights. | |
368 If repository name contains "/", all needed repository groups will be created. | |
369 For example "foo/bar/baz" will create groups "foo", "bar" (with "foo" as parent), | |
370 and create "baz" repository with "bar" as group. | |
371 | |
372 INPUT:: | |
373 | |
374 api_key : "<api_key>" | |
375 method : "create_repo" | |
376 args: { | |
377 "name" : "<name>", | |
378 "owner_name" : "<ownername>", | |
379 "description" : "<description> = ''", | |
380 "repo_type" : "<type> = 'hg'", | |
381 "private" : "<bool> = False" | |
382 } | |
383 | |
384 OUTPUT:: | |
385 | |
386 result: None | |
387 error: null | |
388 | |
389 add_user_to_repo | |
390 ---------------- | |
391 | |
392 Add a user to a repository. This command can be executed only using api_key | |
393 belonging to user with admin rights. | |
394 If "perm" is None, user will be removed from the repository. | |
395 | |
396 INPUT:: | |
397 | |
398 api_key : "<api_key>" | |
399 method : "add_user_to_repo" | |
400 args: { | |
401 "repo_name" : "<reponame>", | |
1810
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
402 "username" : "<username>", |
1793
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
403 "perm" : "(None|repository.(read|write|admin))", |
1592 | 404 } |
405 | |
406 OUTPUT:: | |
407 | |
408 result: None | |
409 error: null | |
1793
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
410 |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
411 add_users_group_to_repo |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
412 ----------------------- |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
413 |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
414 Add a users group to a repository. This command can be executed only using |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
415 api_key belonging to user with admin rights. If "perm" is None, group will |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
416 be removed from the repository. |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
417 |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
418 INPUT:: |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
419 |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
420 api_key : "<api_key>" |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
421 method : "add_users_group_to_repo" |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
422 args: { |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
423 "repo_name" : "<reponame>", |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
424 "group_name" : "<groupname>", |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
425 "perm" : "(None|repository.(read|write|admin))", |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1708
diff
changeset
|
426 } |