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