Mercurial > kallithea

comparison docs/api/api.rst @ 2531:d80a68e2ebcc beta

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
return proper id from users_group update api docs
author Marcin Kuzminski <marcin@python-works.com>
date Sun, 01 Jul 2012 23:36:03 +0200
parents 374693af2849
children 4565e655ea2a
comparison
equal deleted inserted replaced
2530:f17e001cc6cc 2531:d80a68e2ebcc
5 === 5 ===
6 6
7 7
8 Starting from RhodeCode version 1.2 a simple API was implemented. 8 Starting from RhodeCode version 1.2 a simple API was implemented.
9 There's a single schema for calling all api methods. API is implemented 9 There's a single schema for calling all api methods. API is implemented
10 with JSON protocol both ways. An url to send API request in RhodeCode is 10 with JSON protocol both ways. An url to send API request to RhodeCode is
11 <your_server>/_admin/api 11 <your_server>/_admin/api
12 12
13 API ACCESS FOR WEB VIEWS 13 API ACCESS FOR WEB VIEWS
14 ++++++++++++++++++++++++ 14 ++++++++++++++++++++++++
15 15
61 61
62 62
63 API CLIENT 63 API CLIENT
64 ++++++++++ 64 ++++++++++
65 65
66 From version 1.4 RhodeCode adds a binary script that allows to easily 66 From version 1.4 RhodeCode adds a script that allows to easily
67 communicate with API. After installing RhodeCode a `rhodecode-api` script 67 communicate with API. After installing RhodeCode a `rhodecode-api` script
68 will be available. 68 will be available.
69 69
70 To get started quickly simply run:: 70 To get started quickly simply run::
71 71
115 115
116 id : <id_for_response> 116 id : <id_for_response>
117 api_key : "<api_key>" 117 api_key : "<api_key>"
118 method : "pull" 118 method : "pull"
119 args : { 119 args : {
120 "repo_name" : "<reponame>" 120 "repoid" : "<reponame or repo_id>"
121 } 121 }
122 122
123 OUTPUT:: 123 OUTPUT::
124 124
125 result : "Pulled from <reponame>" 125 id : <id_given_in_input>
126 result : "Pulled from `<reponame>`"
126 error : null 127 error : null
127 128
128 129
129 get_user 130 get_user
130 -------- 131 --------
143 "userid" : "<username or user_id>" 144 "userid" : "<username or user_id>"
144 } 145 }
145 146
146 OUTPUT:: 147 OUTPUT::
147 148
149 id : <id_given_in_input>
148 result: None if user does not exist or 150 result: None if user does not exist or
149 { 151 {
150 "id" : "<id>", 152 "user_id" : "<user_id>",
151 "username" : "<username>", 153 "username" : "<username>",
152 "firstname": "<firstname>", 154 "firstname": "<firstname>",
153 "lastname" : "<lastname>", 155 "lastname" : "<lastname>",
154 "email" : "<email>", 156 "email" : "<email>",
155 "emails": "<list_of_all_additional_emails>", 157 "emails": "<list_of_all_additional_emails>",
183 method : "get_users" 185 method : "get_users"
184 args : { } 186 args : { }
185 187
186 OUTPUT:: 188 OUTPUT::
187 189
190 id : <id_given_in_input>
188 result: [ 191 result: [
189 { 192 {
190 "id" : "<id>", 193 "user_id" : "<user_id>",
191 "username" : "<username>", 194 "username" : "<username>",
192 "firstname": "<firstname>", 195 "firstname": "<firstname>",
193 "lastname" : "<lastname>", 196 "lastname" : "<lastname>",
194 "email" : "<email>", 197 "email" : "<email>",
198 "emails": "<list_of_all_additional_emails>",
195 "active" : "<bool>", 199 "active" : "<bool>",
196 "admin" :  "<bool>", 200 "admin" :  "<bool>",
197 "ldap_dn" : "<ldap_dn>", 201 "ldap_dn" : "<ldap_dn>",
198 "last_login": "<last_login>", 202 "last_login": "<last_login>",
199 }, 203 },
214 id : <id_for_response> 218 id : <id_for_response>
215 api_key : "<api_key>" 219 api_key : "<api_key>"
216 method : "create_user" 220 method : "create_user"
217 args : { 221 args : {
218 "username" : "<username>", 222 "username" : "<username>",
223 "email" : "<useremail>",
219 "password" : "<password>", 224 "password" : "<password>",
220 "email" : "<useremail>", 225 "firstname" : "<firstname> = Optional(None)",
221 "firstname" : "<firstname> = None", 226 "lastname" : "<lastname> = Optional(None)",
222 "lastname" : "<lastname> = None", 227 "active" : "<bool> = Optional(True)",
223 "active" : "<bool> = True", 228 "admin" : "<bool> = Optional(False)",
224 "admin" : "<bool> = False", 229 "ldap_dn" : "<ldap_dn> = Optional(None)"
225 "ldap_dn" : "<ldap_dn> = None" 230 }
226 } 231
227 232 OUTPUT::
228 OUTPUT:: 233
229 234 id : <id_given_in_input>
230 result: { 235 result: {
231 "id" : "<new_user_id>", 236 "msg" : "created new user `<username>`",
232 "msg" : "created new user <username>",
233 "user": { 237 "user": {
234 "id" : "<id>", 238 "user_id" : "<user_id>",
235 "username" : "<username>", 239 "username" : "<username>",
236 "firstname": "<firstname>", 240 "firstname": "<firstname>",
237 "lastname" : "<lastname>", 241 "lastname" : "<lastname>",
238 "email" : "<email>", 242 "email" : "<email>",
243 "emails": "<list_of_all_additional_emails>",
239 "active" : "<bool>", 244 "active" : "<bool>",
240 "admin" :  "<bool>", 245 "admin" :  "<bool>",
241 "ldap_dn" : "<ldap_dn>", 246 "ldap_dn" : "<ldap_dn>",
242 "last_login": "<last_login>", 247 "last_login": "<last_login>",
243 }, 248 },
257 id : <id_for_response> 262 id : <id_for_response>
258 api_key : "<api_key>" 263 api_key : "<api_key>"
259 method : "update_user" 264 method : "update_user"
260 args : { 265 args : {
261 "userid" : "<user_id or username>", 266 "userid" : "<user_id or username>",
262 "username" : "<username>", 267 "username" : "<username> = Optional",
263 "password" : "<password>", 268 "email" : "<useremail> = Optional",
264 "email" : "<useremail>", 269 "password" : "<password> = Optional",
265 "firstname" : "<firstname>", 270 "firstname" : "<firstname> = Optional",
266 "lastname" : "<lastname>", 271 "lastname" : "<lastname> = Optional",
267 "active" : "<bool>", 272 "active" : "<bool> = Optional",
268 "admin" : "<bool>", 273 "admin" : "<bool> = Optional",
269 "ldap_dn" : "<ldap_dn>" 274 "ldap_dn" : "<ldap_dn> = Optional"
270 } 275 }
271 276
272 OUTPUT:: 277 OUTPUT::
273 278
274 result: { 279 id : <id_given_in_input>
275 "id" : "<edited_user_id>", 280 result: {
276 "msg" : "updated user ID:<userid> <username>", 281 "msg" : "updated user ID:<userid> <username>",
277 "user": { 282 "user": {
278 "id" : "<id>", 283 "user_id" : "<user_id>",
279 "username" : "<username>", 284 "username" : "<username>",
280 "firstname": "<firstname>", 285 "firstname": "<firstname>",
281 "lastname" : "<lastname>", 286 "lastname" : "<lastname>",
282 "email" : "<email>", 287 "email" : "<email>",
288 "emails": "<list_of_all_additional_emails>",
283 "active" : "<bool>", 289 "active" : "<bool>",
284 "admin" :  "<bool>", 290 "admin" :  "<bool>",
285 "ldap_dn" : "<ldap_dn>", 291 "ldap_dn" : "<ldap_dn>",
286 "last_login": "<last_login>", 292 "last_login": "<last_login>",
287 }, 293 },
306 "userid" : "<user_id or username>", 312 "userid" : "<user_id or username>",
307 } 313 }
308 314
309 OUTPUT:: 315 OUTPUT::
310 316
311 result: { 317 id : <id_given_in_input>
312 "id" : "<edited_user_id>", 318 result: {
313 "msg" : "deleted user ID:<userid> <username>" 319 "msg" : "deleted user ID:<userid> <username>",
320 "user": null
314 } 321 }
315 error: null 322 error: null
316 323
317 324
318 get_users_group 325 get_users_group
326 333
327 id : <id_for_response> 334 id : <id_for_response>
328 api_key : "<api_key>" 335 api_key : "<api_key>"
329 method : "get_users_group" 336 method : "get_users_group"
330 args : { 337 args : {
331 "group_name" : "<name>" 338 "usersgroupid" : "<users group id or name>"
332 } 339 }
333 340
334 OUTPUT:: 341 OUTPUT::
335 342
343 id : <id_given_in_input>
336 result : None if group not exist 344 result : None if group not exist
337 { 345 {
338 "id" : "<id>", 346 "users_group_id" : "<id>",
339 "group_name" : "<groupname>", 347 "group_name" : "<groupname>",
340 "active": "<bool>", 348 "active": "<bool>",
341 "members" : [ 349 "members" : [
342 { "id" : "<userid>", 350 {
351 "user_id" : "<user_id>",
343 "username" : "<username>", 352 "username" : "<username>",
344 "firstname": "<firstname>", 353 "firstname": "<firstname>",
345 "lastname" : "<lastname>", 354 "lastname" : "<lastname>",
346 "email" : "<email>", 355 "email" : "<email>",
356 "emails": "<list_of_all_additional_emails>",
347 "active" : "<bool>", 357 "active" : "<bool>",
348 "admin" :  "<bool>", 358 "admin" :  "<bool>",
349 "ldap" : "<ldap_dn>" 359 "ldap_dn" : "<ldap_dn>",
360 "last_login": "<last_login>",
350 }, 361 },
351 … 362 …
352 ] 363 ]
353 } 364 }
354 error : null 365 error : null
368 method : "get_users_groups" 379 method : "get_users_groups"
369 args : { } 380 args : { }
370 381
371 OUTPUT:: 382 OUTPUT::
372 383
384 id : <id_given_in_input>
373 result : [ 385 result : [
374 { 386 {
375 "id" : "<id>", 387 "users_group_id" : "<id>",
376 "group_name" : "<groupname>", 388 "group_name" : "<groupname>",
377 "active": "<bool>", 389 "active": "<bool>",
378 "members" : [ 390 "members" : [
379 { 391 {
380 "id" : "<userid>", 392 "user_id" : "<user_id>",
381 "username" : "<username>", 393 "username" : "<username>",
382 "firstname": "<firstname>", 394 "firstname": "<firstname>",
383 "lastname" : "<lastname>", 395 "lastname" : "<lastname>",
384 "email" : "<email>", 396 "email" : "<email>",
385 "active" : "<bool>", 397 "emails": "<list_of_all_additional_emails>",
386 "admin" :  "<bool>", 398 "active" : "<bool>",
387 "ldap" : "<ldap_dn>" 399 "admin" :  "<bool>",
388 }, 400 "ldap_dn" : "<ldap_dn>",
389 … 401 "last_login": "<last_login>",
390 ] 402 },
391 } 403 …
404 ]
405 },
406 …
392 ] 407 ]
393 error : null 408 error : null
394 409
395 410
396 create_users_group 411 create_users_group
405 id : <id_for_response> 420 id : <id_for_response>
406 api_key : "<api_key>" 421 api_key : "<api_key>"
407 method : "create_users_group" 422 method : "create_users_group"
408 args: { 423 args: {
409 "group_name": "<groupname>", 424 "group_name": "<groupname>",
410 "active":"<bool> = True" 425 "active":"<bool> = Optional(True)"
411 } 426 }
412 427
413 OUTPUT:: 428 OUTPUT::
414 429
415 result: { 430 id : <id_given_in_input>
416 "id": "<newusersgroupid>", 431 result: {
417 "msg": "created new users group <groupname>" 432 "msg": "created new users group `<groupname>`",
433 "users_group": {
434 "users_group_id" : "<id>",
435 "group_name" : "<groupname>",
436 "active": "<bool>",
437 "members" : [
438 {
439 "user_id" : "<user_id>",
440 "username" : "<username>",
441 "firstname": "<firstname>",
442 "lastname" : "<lastname>",
443 "email" : "<email>",
444 "emails": "<list_of_all_additional_emails>",
445 "active" : "<bool>",
446 "admin" :  "<bool>",
447 "ldap_dn" : "<ldap_dn>",
448 "last_login": "<last_login>",
449 },
450 …
451 ]
452 },
418 } 453 }
419 error: null 454 error: null
420 455
421 456
422 add_user_to_users_group 457 add_user_to_users_group
431 466
432 id : <id_for_response> 467 id : <id_for_response>
433 api_key : "<api_key>" 468 api_key : "<api_key>"
434 method : "add_user_users_group" 469 method : "add_user_users_group"
435 args: { 470 args: {
436 "group_name" : "<groupname>", 471 "usersgroupid" : "<users group id or name>",
437 "username" : "<username>" 472 "userid" : "<user_id or username>",
438 } 473 }
439 474
440 OUTPUT:: 475 OUTPUT::
441 476
442 result: { 477 id : <id_given_in_input>
443 "id": "<newusersgroupmemberid>", 478 result: {
444 "success": True|False # depends on if member is in group 479 "success": True|False # depends on if member is in group
445 "msg": "added member <username> to users group <groupname> | 480 "msg": "added member `<username>` to users group `<groupname>` |
446 User is already in that group" 481 User is already in that group"
447 } 482 }
448 error: null 483 error: null
449 484
450 485
460 495
461 id : <id_for_response> 496 id : <id_for_response>
462 api_key : "<api_key>" 497 api_key : "<api_key>"
463 method : "remove_user_from_users_group" 498 method : "remove_user_from_users_group"
464 args: { 499 args: {
465 "group_name" : "<groupname>", 500 "usersgroupid" : "<users group id or name>",
466 "username" : "<username>" 501 "userid" : "<user_id or username>",
467 } 502 }
468 503
469 OUTPUT:: 504 OUTPUT::
470 505
506 id : <id_given_in_input>
471 result: { 507 result: {
472 "success": True|False, # depends on if member is in group 508 "success": True|False, # depends on if member is in group
473 "msg": "removed member <username> from users group <groupname> | 509 "msg": "removed member <username> from users group <groupname> |
474 User wasn't in group" 510 User wasn't in group"
475 } 511 }
493 "repoid" : "<reponame or repo_id>" 529 "repoid" : "<reponame or repo_id>"
494 } 530 }
495 531
496 OUTPUT:: 532 OUTPUT::
497 533
534 id : <id_given_in_input>
498 result: None if repository does not exist or 535 result: None if repository does not exist or
499 { 536 {
500 "id" : "<id>", 537 "repo_id" : "<repo_id>",
501 "repo_name" : "<reponame>" 538 "repo_name" : "<reponame>"
502 "type" : "<type>", 539 "repo_type" : "<repo_type>",
503 "description" : "<description>",
504 "clone_uri" : "<clone_uri>", 540 "clone_uri" : "<clone_uri>",
505 "private": : "<bool>", 541 "private": : "<bool>",
506 "created_on" : "<datetimecreated>", 542 "created_on" : "<datetimecreated>",
543 "description" : "<description>",
544 "landing_rev": "<landing_rev>",
545 "owner": "<repo_owner>",
546 "fork_of": "<name_of_fork_parent>",
507 "members" : [ 547 "members" : [
508 { 548 {
509 "type": "user", 549 "type": "user",
510 "id" : "<userid>", 550 "user_id" : "<user_id>",
511 "username" : "<username>", 551 "username" : "<username>",
512 "firstname": "<firstname>", 552 "firstname": "<firstname>",
513 "lastname" : "<lastname>", 553 "lastname" : "<lastname>",
514 "email" : "<email>", 554 "email" : "<email>",
515 "active" : "<bool>", 555 "emails": "<list_of_all_additional_emails>",
516 "admin" :  "<bool>", 556 "active" : "<bool>",
517 "ldap" : "<ldap_dn>", 557 "admin" :  "<bool>",
558 "ldap_dn" : "<ldap_dn>",
559 "last_login": "<last_login>",
518 "permission" : "repository.(read|write|admin)" 560 "permission" : "repository.(read|write|admin)"
519 }, 561 },
520 … 562 …
521 { 563 {
522 "type": "users_group", 564 "type": "users_group",
545 method : "get_repos" 587 method : "get_repos"
546 args: { } 588 args: { }
547 589
548 OUTPUT:: 590 OUTPUT::
549 591
592 id : <id_given_in_input>
550 result: [ 593 result: [
551 { 594 {
552 "id" : "<id>", 595 "repo_id" : "<repo_id>",
553 "repo_name" : "<reponame>" 596 "repo_name" : "<reponame>"
554 "type" : "<type>", 597 "repo_type" : "<repo_type>",
555 "description" : "<description>",
556 "clone_uri" : "<clone_uri>", 598 "clone_uri" : "<clone_uri>",
557 "private": : "<bool>", 599 "private": : "<bool>",
558 "created_on" : "<datetimecreated>", 600 "created_on" : "<datetimecreated>",
601 "description" : "<description>",
602 "landing_rev": "<landing_rev>",
603 "owner": "<repo_owner>",
604 "fork_of": "<name_of_fork_parent>",
559 }, 605 },
560 … 606 …
561 ] 607 ]
562 error: null 608 error: null
563 609
575 621
576 id : <id_for_response> 622 id : <id_for_response>
577 api_key : "<api_key>" 623 api_key : "<api_key>"
578 method : "get_repo_nodes" 624 method : "get_repo_nodes"
579 args: { 625 args: {
580 "repo_name" : "<reponame>", 626 "repoid" : "<reponame or repo_id>"
581 "revision" : "<revision>", 627 "revision" : "<revision>",
582 "root_path" : "<root_path>", 628 "root_path" : "<root_path>",
583 "ret_type" : "<ret_type>" = 'all' 629 "ret_type" : "<ret_type> = Optional('all')"
584 } 630 }
585 631
586 OUTPUT:: 632 OUTPUT::
587 633
634 id : <id_given_in_input>
588 result: [ 635 result: [
589 { 636 {
590 "name" : "<name>" 637 "name" : "<name>"
591 "type" : "<type>", 638 "type" : "<type>",
592 }, 639 },
610 id : <id_for_response> 657 id : <id_for_response>
611 api_key : "<api_key>" 658 api_key : "<api_key>"
612 method : "create_repo" 659 method : "create_repo"
613 args: { 660 args: {
614 "repo_name" : "<reponame>", 661 "repo_name" : "<reponame>",
615 "owner_name" : "<ownername>", 662 "owner" : "<onwer_name_or_id>",
616 "description" : "<description> = ''", 663 "repo_type" : "<repo_type>",
617 "repo_type" : "<type> = 'hg'", 664 "description" : "<description> = Optional('')",
618 "private" : "<bool> = False", 665 "private" : "<bool> = Optional(False)",
619 "clone_uri" : "<clone_uri> = None", 666 "clone_uri" : "<clone_uri> = Optional(None)",
620 } 667 "landing_rev" : "<landing_rev> = Optional('tip')",
621 668 }
622 OUTPUT:: 669
623 670 OUTPUT::
624 result: { 671
625 "id": "<newrepoid>", 672 id : <id_given_in_input>
626 "msg": "Created new repository <reponame>", 673 result: {
674 "msg": "Created new repository `<reponame>`",
627 "repo": { 675 "repo": {
628 "id" : "<id>", 676 "repo_id" : "<repo_id>",
629 "repo_name" : "<reponame>" 677 "repo_name" : "<reponame>"
630 "type" : "<type>", 678 "repo_type" : "<repo_type>",
631 "description" : "<description>",
632 "clone_uri" : "<clone_uri>", 679 "clone_uri" : "<clone_uri>",
633 "private": : "<bool>", 680 "private": : "<bool>",
634 "created_on" : "<datetimecreated>", 681 "created_on" : "<datetimecreated>",
682 "description" : "<description>",
683 "landing_rev": "<landing_rev>",
684 "owner": "<repo_owner>",
685 "fork_of": "<name_of_fork_parent>",
635 }, 686 },
636 } 687 }
637 error: null 688 error: null
638 689
639 690
648 699
649 id : <id_for_response> 700 id : <id_for_response>
650 api_key : "<api_key>" 701 api_key : "<api_key>"
651 method : "delete_repo" 702 method : "delete_repo"
652 args: { 703 args: {
653 "repo_name" : "<reponame>", 704 "repoid" : "<reponame or repo_id>"
654 } 705 }
655 706
656 OUTPUT:: 707 OUTPUT::
657 708
658 result: { 709 id : <id_given_in_input>
659 "msg": "Deleted repository <reponame>", 710 result: {
711 "msg": "Deleted repository `<reponame>`",
712 "success": true
660 } 713 }
661 error: null 714 error: null
662 715
663 716
664 grant_user_permission 717 grant_user_permission
673 726
674 id : <id_for_response> 727 id : <id_for_response>
675 api_key : "<api_key>" 728 api_key : "<api_key>"
676 method : "grant_user_permission" 729 method : "grant_user_permission"
677 args: { 730 args: {
678 "repo_name" : "<reponame>", 731 "repoid" : "<reponame or repo_id>"
679 "username" : "<username>", 732 "userid" : "<username or user_id>"
680 "perm" : "(repository.(none|read|write|admin))", 733 "perm" : "(repository.(none|read|write|admin))",
681 } 734 }
682 735
683 OUTPUT:: 736 OUTPUT::
684 737
685 result: { 738 id : <id_given_in_input>
686 "msg" : "Granted perm: <perm> for user: <username> in repo: <reponame>" 739 result: {
740 "msg" : "Granted perm: `<perm>` for user: `<username>` in repo: `<reponame>`",
741 "success": true
687 } 742 }
688 error: null 743 error: null
689 744
690 745
691 revoke_user_permission 746 revoke_user_permission
699 754
700 id : <id_for_response> 755 id : <id_for_response>
701 api_key : "<api_key>" 756 api_key : "<api_key>"
702 method : "revoke_user_permission" 757 method : "revoke_user_permission"
703 args: { 758 args: {
704 "repo_name" : "<reponame>", 759 "repoid" : "<reponame or repo_id>"
705 "username" : "<username>", 760 "userid" : "<username or user_id>"
706 } 761 }
707 762
708 OUTPUT:: 763 OUTPUT::
709 764
710 result: { 765 id : <id_given_in_input>
711 "msg" : "Revoked perm for user: <suername> in repo: <reponame>" 766 result: {
767 "msg" : "Revoked perm for user: `<username>` in repo: `<reponame>`",
768 "success": true
712 } 769 }
713 error: null 770 error: null
714 771
715 772
716 grant_users_group_permission 773 grant_users_group_permission
725 782
726 id : <id_for_response> 783 id : <id_for_response>
727 api_key : "<api_key>" 784 api_key : "<api_key>"
728 method : "grant_users_group_permission" 785 method : "grant_users_group_permission"
729 args: { 786 args: {
730 "repo_name" : "<reponame>", 787 "repoid" : "<reponame or repo_id>"
731 "group_name" : "<usersgroupname>", 788 "usersgroupid" : "<users group id or name>"
732 "perm" : "(repository.(none|read|write|admin))", 789 "perm" : "(repository.(none|read|write|admin))",
733 } 790 }
734 791
735 OUTPUT:: 792 OUTPUT::
736 793
737 result: { 794 id : <id_given_in_input>
738 "msg" : "Granted perm: <perm> for group: <usersgroupname> in repo: <reponame>" 795 result: {
796 "msg" : "Granted perm: `<perm>` for group: `<usersgroupname>` in repo: `<reponame>`",
797 "success": true
739 } 798 }
740 error: null 799 error: null
741 800
742 801
743 revoke_users_group_permission 802 revoke_users_group_permission
750 809
751 id : <id_for_response> 810 id : <id_for_response>
752 api_key : "<api_key>" 811 api_key : "<api_key>"
753 method : "revoke_users_group_permission" 812 method : "revoke_users_group_permission"
754 args: { 813 args: {
755 "repo_name" : "<reponame>", 814 "repoid" : "<reponame or repo_id>"
756 "users_group" : "<usersgroupname>", 815 "usersgroupid" : "<users group id or name>"
757 } 816 }
758 817
759 OUTPUT:: 818 OUTPUT::
760 819
761 result: { 820 id : <id_given_in_input>
762 "msg" : "Revoked perm for group: <usersgroupname> in repo: <reponame>" 821 result: {
763 } 822 "msg" : "Revoked perm for group: `<usersgroupname>` in repo: `<reponame>`",
764 error: null 823 "success": true
824 }
825 error: null