Mercurial > kallithea

comparison docs/api/api.rst @ 2031:82a88013a3fd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merge 1.3 into stable
author Marcin Kuzminski <marcin@python-works.com>
date Sun, 26 Feb 2012 17:25:09 +0200
parents 54e84659cb3a 14dffcfebb02
children 934906f028b5
comparison
equal deleted inserted replaced
2005:ab0e122b38a7 2031:82a88013a3fd
24 API ACCESS 24 API ACCESS
25 ++++++++++ 25 ++++++++++
26 26
27 All clients are required to send JSON-RPC spec JSON data:: 27 All clients are required to send JSON-RPC spec JSON data::
28 28
29 { 29 {
30 "id:<id>,
30 "api_key":"<api_key>", 31 "api_key":"<api_key>",
31 "method":"<method_name>", 32 "method":"<method_name>",
32 "args":{"<arg_key>":"<arg_val>"} 33 "args":{"<arg_key>":"<arg_val>"}
33 } 34 }
34 35
35 Example call for autopulling remotes repos using curl:: 36 Example call for autopulling remotes repos using curl::
36 curl https://server.com/_admin/api -X POST -H 'content-type:text/plain' --data-binary '{"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}' 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"}}'
37 38
38 Simply provide 39 Simply provide
40 - *id* A value of any type, which is used to match the response with the request that it is replying to.
39 - *api_key* for access and permission validation. 41 - *api_key* for access and permission validation.
40 - *method* is name of method to call 42 - *method* is name of method to call
41 - *args* is an key:value list of arguments to pass to method 43 - *args* is an key:value list of arguments to pass to method
42 44
43 .. note:: 45 .. note::
45 api_key can be found in your user account page 47 api_key can be found in your user account page
46 48
47 49
48 RhodeCode API will return always a JSON-RPC response:: 50 RhodeCode API will return always a JSON-RPC response::
49 51
50 { 52 {
53 "id":<id>,
51 "result": "<result>", 54 "result": "<result>",
52 "error": null 55 "error": null
53 } 56 }
54 57
55 All responses from API will be `HTTP/1.0 200 OK`, if there's an error while 58 All responses from API will be `HTTP/1.0 200 OK`, if there's an error while
70 INPUT:: 73 INPUT::
71 74
72 api_key : "<api_key>" 75 api_key : "<api_key>"
73 method : "pull" 76 method : "pull"
74 args : { 77 args : {
75 "repo" : "<repo_name>" 78 "repo_name" : "<reponame>"
76 } 79 }
77 80
78 OUTPUT:: 81 OUTPUT::
79 82
80 result : "Pulled from <repo_name>" 83 result : "Pulled from <reponame>"
81 error : null 84 error : null
85
86
87 get_user
88 --------
89
90 Get's an user by username or user_id, 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
95 INPUT::
96
97 api_key : "<api_key>"
98 method : "get_user"
99 args : {
100 "userid" : "<username or user_id>"
101 }
102
103 OUTPUT::
104
105 result: None if user does not exist or
106 {
107 "id" : "<id>",
108 "username" : "<username>",
109 "firstname": "<firstname>",
110 "lastname" : "<lastname>",
111 "email" : "<email>",
112 "active" : "<bool>",
113 "admin" :  "<bool>",
114 "ldap_dn" : "<ldap_dn>"
115 }
116
117 error: null
82 118
83 119
84 get_users 120 get_users
85 --------- 121 ---------
86 122
87 Lists all existing users. This command can be executed only using api_key 123 Lists all existing users. This command can be executed only using api_key
88 belonging to user with admin rights. 124 belonging to user with admin rights.
125
89 126
90 INPUT:: 127 INPUT::
91 128
92 api_key : "<api_key>" 129 api_key : "<api_key>"
93 method : "get_users" 130 method : "get_users"
102 "firstname": "<firstname>", 139 "firstname": "<firstname>",
103 "lastname" : "<lastname>", 140 "lastname" : "<lastname>",
104 "email" : "<email>", 141 "email" : "<email>",
105 "active" : "<bool>", 142 "active" : "<bool>",
106 "admin" :  "<bool>", 143 "admin" :  "<bool>",
107 "ldap" : "<ldap_dn>" 144 "ldap_dn" : "<ldap_dn>"
108 }, 145 },
109 … 146 …
110 ] 147 ]
111 error: null 148 error: null
112 149
150
113 create_user 151 create_user
114 ----------- 152 -----------
115 153
116 Creates new user or updates current one if such user exists. This command can 154 Creates new user. This command can
117 be executed only using api_key belonging to user with admin rights. 155 be executed only using api_key belonging to user with admin rights.
156
118 157
119 INPUT:: 158 INPUT::
120 159
121 api_key : "<api_key>" 160 api_key : "<api_key>"
122 method : "create_user" 161 method : "create_user"
123 args : { 162 args : {
124 "username" : "<username>", 163 "username" : "<username>",
125 "password" : "<password>", 164 "password" : "<password>",
126 "firstname" : "<firstname>", 165 "email" : "<useremail>",
127 "lastname" : "<lastname>", 166 "firstname" : "<firstname> = None",
128 "email" : "<useremail>" 167 "lastname" : "<lastname> = None",
129 "active" : "<bool> = True", 168 "active" : "<bool> = True",
130 "admin" : "<bool> = False", 169 "admin" : "<bool> = False",
131 "ldap_dn" : "<ldap_dn> = None" 170 "ldap_dn" : "<ldap_dn> = None"
132 } 171 }
133 172
134 OUTPUT:: 173 OUTPUT::
135 174
136 result: { 175 result: {
176 "id" : "<new_user_id>",
137 "msg" : "created new user <username>" 177 "msg" : "created new user <username>"
138 } 178 }
139 error: null 179 error: null
180
181
182 update_user
183 -----------
184
185 updates current one if such user exists. This command can
186 be executed only using api_key belonging to user with admin rights.
187
188
189 INPUT::
190
191 api_key : "<api_key>"
192 method : "update_user"
193 args : {
194 "userid" : "<user_id or username>",
195 "username" : "<username>",
196 "password" : "<password>",
197 "email" : "<useremail>",
198 "firstname" : "<firstname>",
199 "lastname" : "<lastname>",
200 "active" : "<bool>",
201 "admin" : "<bool>",
202 "ldap_dn" : "<ldap_dn>"
203 }
204
205 OUTPUT::
206
207 result: {
208 "id" : "<edited_user_id>",
209 "msg" : "updated user <username>"
210 }
211 error: null
212
213
214 get_users_group
215 ---------------
216
217 Gets an existing users group. This command can be executed only using api_key
218 belonging to user with admin rights.
219
220
221 INPUT::
222
223 api_key : "<api_key>"
224 method : "get_users_group"
225 args : {
226 "group_name" : "<name>"
227 }
228
229 OUTPUT::
230
231 result : None if group not exist
232 {
233 "id" : "<id>",
234 "group_name" : "<groupname>",
235 "active": "<bool>",
236 "members" : [
237 { "id" : "<userid>",
238 "username" : "<username>",
239 "firstname": "<firstname>",
240 "lastname" : "<lastname>",
241 "email" : "<email>",
242 "active" : "<bool>",
243 "admin" :  "<bool>",
244 "ldap" : "<ldap_dn>"
245 },
246 …
247 ]
248 }
249 error : null
250
140 251
141 get_users_groups 252 get_users_groups
142 ---------------- 253 ----------------
143 254
144 Lists all existing users groups. This command can be executed only using api_key 255 Lists all existing users groups. This command can be executed only using
145 belonging to user with admin rights. 256 api_key belonging to user with admin rights.
257
146 258
147 INPUT:: 259 INPUT::
148 260
149 api_key : "<api_key>" 261 api_key : "<api_key>"
150 method : "get_users_groups" 262 method : "get_users_groups"
152 264
153 OUTPUT:: 265 OUTPUT::
154 266
155 result : [ 267 result : [
156 { 268 {
157 "id" : "<id>", 269 "id" : "<id>",
158 "name" : "<name>", 270 "group_name" : "<groupname>",
159 "active": "<bool>", 271 "active": "<bool>",
160 "members" : [ 272 "members" : [
161 { 273 {
162 "id" : "<userid>", 274 "id" : "<userid>",
163 "username" : "<username>", 275 "username" : "<username>",
164 "firstname": "<firstname>", 276 "firstname": "<firstname>",
172 ] 284 ]
173 } 285 }
174 ] 286 ]
175 error : null 287 error : null
176 288
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 {
195 "id" : "<id>",
196 "name" : "<name>",
197 "active": "<bool>",
198 "members" : [
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 ]
210 }
211 error : null
212 289
213 create_users_group 290 create_users_group
214 ------------------ 291 ------------------
215 292
216 Creates new users group. This command can be executed only using api_key 293 Creates new users group. This command can be executed only using api_key
217 belonging to user with admin rights 294 belonging to user with admin rights
218 295
296
219 INPUT:: 297 INPUT::
220 298
221 api_key : "<api_key>" 299 api_key : "<api_key>"
222 method : "create_users_group" 300 method : "create_users_group"
223 args: { 301 args: {
224 "name": "<name>", 302 "group_name": "<groupname>",
225 "active":"<bool> = True" 303 "active":"<bool> = True"
226 } 304 }
227 305
228 OUTPUT:: 306 OUTPUT::
229 307
230 result: { 308 result: {
231 "id": "<newusersgroupid>", 309 "id": "<newusersgroupid>",
232 "msg": "created new users group <name>" 310 "msg": "created new users group <groupname>"
233 } 311 }
234 error: null 312 error: null
313
235 314
236 add_user_to_users_group 315 add_user_to_users_group
237 ----------------------- 316 -----------------------
238 317
239 Adds a user to a users group. This command can be executed only using api_key 318 Adds a user to a users group. If user exists in that group success will be
319 `false`. This command can be executed only using api_key
240 belonging to user with admin rights 320 belonging to user with admin rights
241 321
322
242 INPUT:: 323 INPUT::
243 324
244 api_key : "<api_key>" 325 api_key : "<api_key>"
245 method : "add_user_users_group" 326 method : "add_user_users_group"
246 args: { 327 args: {
247 "group_name" : "<groupname>", 328 "group_name" : "<groupname>",
248 "user_name" : "<username>" 329 "username" : "<username>"
249 } 330 }
250 331
251 OUTPUT:: 332 OUTPUT::
252 333
253 result: { 334 result: {
254 "id": "<newusersgroupmemberid>", 335 "id": "<newusersgroupmemberid>",
255 "msg": "created new users group member" 336 "success": True|False # depends on if member is in group
256 } 337 "msg": "added member <username> to users group <groupname> |
257 error: null 338 User is already in that group"
258 339 }
259 get_repos 340 error: null
260 --------- 341
261 342
262 Lists all existing repositories. This command can be executed only using api_key 343 remove_user_from_users_group
263 belonging to user with admin rights 344 ----------------------------
264 345
265 INPUT:: 346 Removes a user from a users group. If user is not in given group success will
266 347 be `false`. This command can be executed only
267 api_key : "<api_key>" 348 using api_key belonging to user with admin rights
268 method : "get_repos" 349
269 args: { } 350
270 351 INPUT::
271 OUTPUT:: 352
272 353 api_key : "<api_key>"
273 result: [ 354 method : "remove_user_from_users_group"
274 { 355 args: {
275 "id" : "<id>", 356 "group_name" : "<groupname>",
276 "name" : "<name>" 357 "username" : "<username>"
277 "type" : "<type>", 358 }
278 "description" : "<description>" 359
279 }, 360 OUTPUT::
280 … 361
281 ] 362 result: {
282 error: null 363 "success": True|False, # depends on if member is in group
364 "msg": "removed member <username> from users group <groupname> |
365 User wasn't in group"
366 }
367 error: null
368
283 369
284 get_repo 370 get_repo
285 -------- 371 --------
286 372
287 Gets an existing repository. This command can be executed only using api_key 373 Gets an existing repository by it's name or repository_id. This command can
288 belonging to user with admin rights 374 be executed only using api_key belonging to user with admin rights.
375
289 376
290 INPUT:: 377 INPUT::
291 378
292 api_key : "<api_key>" 379 api_key : "<api_key>"
293 method : "get_repo" 380 method : "get_repo"
294 args: { 381 args: {
295 "name" : "<name>" 382 "repoid" : "<reponame or repo_id>"
296 } 383 }
297 384
298 OUTPUT:: 385 OUTPUT::
299 386
300 result: None if repository not exist 387 result: None if repository does not exist or
301 { 388 {
302 "id" : "<id>", 389 "id" : "<id>",
303 "name" : "<name>" 390 "repo_name" : "<reponame>"
304 "type" : "<type>", 391 "type" : "<type>",
305 "description" : "<description>", 392 "description" : "<description>",
306 "members" : [ 393 "members" : [
307 { "id" : "<userid>", 394 { "id" : "<userid>",
308 "username" : "<username>", 395 "username" : "<username>",
309 "firstname": "<firstname>", 396 "firstname": "<firstname>",
310 "lastname" : "<lastname>", 397 "lastname" : "<lastname>",
311 "email" : "<email>", 398 "email" : "<email>",
312 "active" : "<bool>", 399 "active" : "<bool>",
313 "admin" :  "<bool>", 400 "admin" :  "<bool>",
314 "ldap" : "<ldap_dn>", 401 "ldap" : "<ldap_dn>",
315 "permission" : "repository.(read|write|admin)" 402 "permission" : "repository.(read|write|admin)"
316 }, 403 },
317 … 404 …
318 { 405 {
319 "id" : "<usersgroupid>", 406 "id" : "<usersgroupid>",
320 "name" : "<usersgroupname>", 407 "name" : "<usersgroupname>",
321 "active": "<bool>", 408 "active": "<bool>",
324 … 411 …
325 ] 412 ]
326 } 413 }
327 error: null 414 error: null
328 415
416
417 get_repos
418 ---------
419
420 Lists all existing repositories. This command can be executed only using api_key
421 belonging to user with admin rights
422
423
424 INPUT::
425
426 api_key : "<api_key>"
427 method : "get_repos"
428 args: { }
429
430 OUTPUT::
431
432 result: [
433 {
434 "id" : "<id>",
435 "repo_name" : "<reponame>"
436 "type" : "<type>",
437 "description" : "<description>"
438 },
439 …
440 ]
441 error: null
442
443
444 get_repo_nodes
445 --------------
446
447 returns a list of nodes and it's children in a flat list for a given path
448 at given revision. It's possible to specify ret_type to show only `files` or
449 `dirs`. This command can be executed only using api_key belonging to user
450 with admin rights
451
452
453 INPUT::
454
455 api_key : "<api_key>"
456 method : "get_repo_nodes"
457 args: {
458 "repo_name" : "<reponame>",
459 "revision" : "<revision>",
460 "root_path" : "<root_path>",
461 "ret_type" : "<ret_type>" = 'all'
462 }
463
464 OUTPUT::
465
466 result: [
467 {
468 "name" : "<name>"
469 "type" : "<type>",
470 },
471 …
472 ]
473 error: null
474
475
329 create_repo 476 create_repo
330 ----------- 477 -----------
331 478
332 Creates a repository. This command can be executed only using api_key 479 Creates a repository. This command can be executed only using api_key
333 belonging to user with admin rights. 480 belonging to user with admin rights.
334 If repository name contains "/", all needed repository groups will be created. 481 If repository name contains "/", all needed repository groups will be created.
335 For example "foo/bar/baz" will create groups "foo", "bar" (with "foo" as parent), 482 For example "foo/bar/baz" will create groups "foo", "bar" (with "foo" as parent),
336 and create "baz" repository with "bar" as group. 483 and create "baz" repository with "bar" as group.
337 484
485
338 INPUT:: 486 INPUT::
339 487
340 api_key : "<api_key>" 488 api_key : "<api_key>"
341 method : "create_repo" 489 method : "create_repo"
342 args: { 490 args: {
343 "name" : "<name>", 491 "repo_name" : "<reponame>",
344 "owner_name" : "<ownername>", 492 "owner_name" : "<ownername>",
345 "description" : "<description> = ''", 493 "description" : "<description> = ''",
346 "repo_type" : "<type> = 'hg'", 494 "repo_type" : "<type> = 'hg'",
347 "private" : "<bool> = False" 495 "private" : "<bool> = False",
348 } 496 "clone_uri" : "<clone_uri> = None",
349 497 }
350 OUTPUT:: 498
351 499 OUTPUT::
352 result: None 500
353 error: null 501 result: {
354 502 "id": "<newrepoid>",
355 add_user_to_repo 503 "msg": "Created new repository <reponame>",
356 ---------------- 504 }
357 505 error: null
358 Add a user to a repository. This command can be executed only using api_key 506
507
508 delete_repo
509 -----------
510
511 Deletes a repository. This command can be executed only using api_key
359 belonging to user with admin rights. 512 belonging to user with admin rights.
360 If "perm" is None, user will be removed from the repository. 513
361 514
362 INPUT:: 515 INPUT::
363 516
364 api_key : "<api_key>" 517 api_key : "<api_key>"
365 method : "add_user_to_repo" 518 method : "delete_repo"
519 args: {
520 "repo_name" : "<reponame>",
521 }
522
523 OUTPUT::
524
525 result: {
526 "msg": "Deleted repository <reponame>",
527 }
528 error: null
529
530
531 grant_user_permission
532 ---------------------
533
534 Grant permission for user on given repository, or update existing one
535 if found. This command can be executed only using api_key belonging to user
536 with admin rights.
537
538
539 INPUT::
540
541 api_key : "<api_key>"
542 method : "grant_user_permission"
366 args: { 543 args: {
367 "repo_name" : "<reponame>", 544 "repo_name" : "<reponame>",
368 "user_name" : "<username>", 545 "username" : "<username>",
369 "perm" : "(None|repository.(read|write|admin))", 546 "perm" : "(repository.(none|read|write|admin))",
370 } 547 }
371 548
372 OUTPUT:: 549 OUTPUT::
373 550
374 result: None 551 result: {
375 error: null 552 "msg" : "Granted perm: <perm> for user: <username> in repo: <reponame>"
376 553 }
377 add_users_group_to_repo 554 error: null
378 ----------------------- 555
379 556
380 Add a users group to a repository. This command can be executed only using 557 revoke_user_permission
381 api_key belonging to user with admin rights. If "perm" is None, group will 558 ----------------------
382 be removed from the repository. 559
383 560 Revoke permission for user on given repository. This command can be executed
384 INPUT:: 561 only using api_key belonging to user with admin rights.
385 562
386 api_key : "<api_key>" 563
387 method : "add_users_group_to_repo" 564 INPUT::
565
566 api_key : "<api_key>"
567 method : "revoke_user_permission"
388 args: { 568 args: {
389 "repo_name" : "<reponame>", 569 "repo_name" : "<reponame>",
390 "group_name" : "<groupname>", 570 "username" : "<username>",
391 "perm" : "(None|repository.(read|write|admin))", 571 }
392 } 572
573 OUTPUT::
574
575 result: {
576 "msg" : "Revoked perm for user: <suername> in repo: <reponame>"
577 }
578 error: null
579
580
581 grant_users_group_permission
582 ----------------------------
583
584 Grant permission for users group on given repository, or update
585 existing one if found. This command can be executed only using
586 api_key belonging to user with admin rights.
587
588
589 INPUT::
590
591 api_key : "<api_key>"
592 method : "grant_users_group_permission"
593 args: {
594 "repo_name" : "<reponame>",
595 "group_name" : "<usersgroupname>",
596 "perm" : "(repository.(none|read|write|admin))",
597 }
598
599 OUTPUT::
600
601 result: {
602 "msg" : "Granted perm: <perm> for group: <usersgroupname> in repo: <reponame>"
603 }
604 error: null
605
606
607 revoke_users_group_permission
608 -----------------------------
609
610 Revoke permission for users group on given repository.This command can be
611 executed only using api_key belonging to user with admin rights.
612
613 INPUT::
614
615 api_key : "<api_key>"
616 method : "revoke_users_group_permission"
617 args: {
618 "repo_name" : "<reponame>",
619 "users_group" : "<usersgroupname>",
620 }
621
622 OUTPUT::
623
624 result: {
625 "msg" : "Revoked perm for group: <usersgroupname> in repo: <reponame>"
626 }
627 error: null