Mercurial > kallithea

comparison docs/api/api.rst @ 4879:599fba9967a4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: improve the API documentation
author Mads Kiilerich <madski@unity3d.com>
date Fri, 27 Feb 2015 15:37:46 +0100
parents 88b9cc4ba52f
children 03bbd33bc084
comparison
equal deleted inserted replaced
4878:7f8f576dc0b5 4879:599fba9967a4
3 === 3 ===
4 API 4 API
5 === 5 ===
6 6
7 7
8 Starting from Kallithea version 1.2 a simple API was implemented. 8 Kallithea has a simple JSON RPC API with a single schema for calling all api
9 There's a single schema for calling all api methods. API is implemented 9 methods. Everything is available by sending JSON encoded http(s) requests to
10 with JSON protocol both ways. An url to send API request to Kallithea is 10 <your_server>/_admin/api .
11 <your_server>/_admin/api 11
12 12
13 API ACCESS FOR WEB VIEWS 13 API ACCESS FOR WEB VIEWS
14 ++++++++++++++++++++++++ 14 ++++++++++++++++++++++++
15 15
16 API access can also be turned on for each web view in Kallithea that is 16 API access can also be turned on for each web view in Kallithea that is
17 decorated with `@LoginRequired` decorator. To enable API access simple change 17 decorated with the `@LoginRequired` decorator. Some views use
18 the standard login decorator to `@LoginRequired(api_access=True)`. 18 `@LoginRequired(api_access=True)` and are always available. By default only
19 19 RSS/ATOM feed views are enabled. Other views are
20 To make this operation easier, starting from version 1.7.0 there's a white list 20 only available if they have been white listed. Edit the
21 of views that will have API access enabled. Simply edit `api_access_controllers_whitelist` 21 `api_access_controllers_whitelist` option in your .ini file and define views
22 option in your .ini file, and define views that should have API access enabled. 22 that should have API access enabled.
23 Following example shows how to enable API access to patch/diff raw file and archive 23
24 in Kallithea:: 24 For example, to enable API access to patch/diff raw file and archive::
25 25
26 api_access_controllers_whitelist = 26 api_access_controllers_whitelist =
27 ChangesetController:changeset_patch, 27 ChangesetController:changeset_patch,
28 ChangesetController:changeset_raw, 28 ChangesetController:changeset_raw,
29 FilesController:raw, 29 FilesController:raw,
30 FilesController:archivefile 30 FilesController:archivefile
31 31
32
33 After this change, a Kallithea view can be accessed without login by adding a 32 After this change, a Kallithea view can be accessed without login by adding a
34 GET parameter `?api_key=<api_key>` to url. By default this is only 33 GET parameter `?api_key=<api_key>` to url.
35 enabled on RSS/ATOM feed views. Exposing raw diffs is a good way to integrate with 34
35 Exposing raw diffs is a good way to integrate with
36 3rd party services like code review, or build farms that could download archives. 36 3rd party services like code review, or build farms that could download archives.
37 37
38 38
39 API ACCESS 39 API ACCESS
40 ++++++++++ 40 ++++++++++
41 41
42 All clients are required to send JSON-RPC spec JSON data:: 42 Clients must send JSON encoded JSON-RPC requests::
43 43
44 { 44 {
45 "id:"<id>", 45 "id: "<id>",
46 "api_key":"<api_key>", 46 "api_key": "<api_key>",
47 "method":"<method_name>", 47 "method": "<method_name>",
48 "args":{"<arg_key>":"<arg_val>"} 48 "args": {"<arg_key>": "<arg_val>"}
49 } 49 }
50 50
51 Example call for autopulling remotes repos using curl:: 51 For example, to pull to a local "CPython" mirror using curl::
52
52 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"}}' 53 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"}}'
53 54
54 Simply provide 55 In general, provide
55 - *id* A value of any type, which is used to match the response with the request that it is replying to. 56 - *id*, a value of any type, can be used to match the response with the request that it is replying to.
56 - *api_key* for access and permission validation. 57 - *api_key*, for authentication and permission validation.
57 - *method* is name of method to call 58 - *method*, the name of the method to call - a list of available methods can be found below.
58 - *args* is an key:value list of arguments to pass to method 59 - *args*, the arguments to pass to the method.
59 60
60 .. note:: 61 .. note::
61 62
62 api_key can be found in your user account page 63 api_key can be found or set on the user account page
63 64
64 65 The response to the JSON-RPC API call will always be a JSON structure::
65 Kallithea API will return always a JSON-RPC response::
66 66
67 { 67 {
68 "id":<id>, # matching id sent by request 68 "id":<id>, # the id that was used in the request
69 "result": "<result>"|null, # JSON formatted result, null if any errors 69 "result": "<result>"|null, # JSON formatted result, null if any errors
70 "error": "null"|<error_message> # JSON formatted error (if any) 70 "error": "null"|<error_message> # JSON formatted error (if any)
71 } 71 }
72 72
73 All responses from API will be `HTTP/1.0 200 OK`, if there's an error while 73 All responses from API will be `HTTP/1.0 200 OK`. If there is an error,
74 calling api *error* key from response will contain failure description 74 the reponse will have a failure description in *error* and
75 and result will be null. 75 *result* will be null.
76 76
77 77
78 API CLIENT 78 API CLIENT
79 ++++++++++ 79 ++++++++++
80 80
81 From version 1.4 Kallithea adds a script that allows to easily 81 Kallithea comes with a `kallithea-api` command line tool providing a convenient
82 communicate with API. After installing Kallithea a `kallithea-api` script 82 way to call the JSON-RPC API.
83 will be available. 83
84 84 For example, to call `get_repo`::
85 To get started quickly simply run:: 85
86 86 kallithea-api --apihost=<your.kallithea.server.url> --apikey=<yourapikey> get_repo
87 kallithea-api _create_config --apikey=<youapikey> --apihost=<your.kallithea.server>
88
89 This will create a file named .config in the directory you executed it storing
90 json config file with credentials. You can skip this step and always provide
91 both of the arguments to be able to communicate with server
92
93
94 after that simply run any api command for example get_repo::
95
96 kallithea-api get_repo
97 87
98 calling {"api_key": "<apikey>", "id": 75, "args": {}, "method": "get_repo"} to http://127.0.0.1:5000 88 calling {"api_key": "<apikey>", "id": 75, "args": {}, "method": "get_repo"} to http://127.0.0.1:5000
99 Kallithea said: 89 Kallithea said:
100 {'error': 'Missing non optional `repoid` arg in JSON DATA', 90 {'error': 'Missing non optional `repoid` arg in JSON DATA',
101 'id': 75, 91 'id': 75,
102 'result': None} 92 'result': None}
103 93
104 Ups looks like we forgot to add an argument 94 Oops, looks like we forgot to add an argument. Let's try again, now providing the repoid as parameter::
105
106 Let's try again now giving the repoid as parameters::
107 95
108 kallithea-api get_repo repoid:myrepo 96 kallithea-api get_repo repoid:myrepo
109 97
110 calling {"api_key": "<apikey>", "id": 39, "args": {"repoid": "myrepo"}, "method": "get_repo"} to http://127.0.0.1:5000 98 calling {"api_key": "<apikey>", "id": 39, "args": {"repoid": "myrepo"}, "method": "get_repo"} to http://127.0.0.1:5000
111 Kallithea said: 99 Kallithea said:
112 {'error': None, 100 {'error': None,
113 'id': 39, 101 'id': 39,
114 'result': <json data...>} 102 'result': <json data...>}
115 103
104 To avoid specifying apihost and apikey every time, run::
105
106 kallithea-api --save-config --apihost=<your.kallithea.server.url> --apikey=<yourapikey>
107
108 This will create a `~/.config/kallithea` with the specified hostname and apikey
109 so you don't have to specify them every time.
116 110
117 111
118 API METHODS 112 API METHODS
119 +++++++++++ 113 +++++++++++
120 114
121 115
122 pull 116 pull
123 ---- 117 ----
124 118
125 Pulls given repo from remote location. Can be used to automatically keep 119 Pull the given repo from remote location. Can be used to automatically keep
126 remote repos up to date. This command can be executed only using api_key 120 remote repos up to date.
127 belonging to user with admin rights 121 This command can only be executed using the api_key of a user with admin rights.
128 122
129 INPUT:: 123 INPUT::
130 124
131 id : <id_for_response> 125 id : <id_for_response>
132 api_key : "<api_key>" 126 api_key : "<api_key>"
143 137
144 138
145 rescan_repos 139 rescan_repos
146 ------------ 140 ------------
147 141
148 Dispatch rescan repositories action. If remove_obsolete is set 142 Rescan repositories. If remove_obsolete is set,
149 Kallithea will delete repos that are in database but not in the filesystem. 143 Kallithea will delete repos that are in database but not in the filesystem.
150 This command can be executed only using api_key belonging to user with admin 144 This command can only be executed using the api_key of a user with admin rights.
151 rights.
152 145
153 INPUT:: 146 INPUT::
154 147
155 id : <id_for_response> 148 id : <id_for_response>
156 api_key : "<api_key>" 149 api_key : "<api_key>"
169 162
170 invalidate_cache 163 invalidate_cache
171 ---------------- 164 ----------------
172 165
173 Invalidate cache for repository. 166 Invalidate cache for repository.
174 This command can be executed only using api_key belonging to user with admin 167 This command can only be executed using the api_key of a user with admin rights,
175 rights or regular user that have write or admin or write access to repository. 168 or that of a regular user with admin or write access to the repository.
176 169
177 INPUT:: 170 INPUT::
178 171
179 id : <id_for_response> 172 id : <id_for_response>
180 api_key : "<api_key>" 173 api_key : "<api_key>"
187 180
188 id : <id_given_in_input> 181 id : <id_given_in_input>
189 result : "Caches of repository `<reponame>`" 182 result : "Caches of repository `<reponame>`"
190 error : null 183 error : null
191 184
185
192 lock 186 lock
193 ---- 187 ----
194 188
195 Set locking state on given repository by given user. If userid param is skipped 189 Set the locking state on the given repository by the given user.
196 , then it is set to id of user whos calling this method. If locked param is skipped 190 If param 'userid' is skipped, it is set to the id of the user who is calling this method.
197 then function shows current lock state of given repo. 191 If param 'locked' is skipped, the current lock state of the repository is returned.
198 This command can be executed only using api_key belonging to user with admin 192 This command can only be executed using the api_key of a user with admin rights, or that of a regular user with admin or write access to the repository.
199 rights or regular user that have admin or write access to repository.
200 193
201 INPUT:: 194 INPUT::
202 195
203 id : <id_for_response> 196 id : <id_for_response>
204 api_key : "<api_key>" 197 api_key : "<api_key>"
223 216
224 217
225 get_ip 218 get_ip
226 ------ 219 ------
227 220
228 Shows IP address as seen from Kallithea server, together with all 221 Return IP address as seen from Kallithea server, together with all
229 defined IP addresses for given user. 222 defined IP addresses for given user.
230 This command can be executed only using api_key belonging to user with admin 223 This command can only be executed using the api_key of a user with admin rights.
231 rights.
232 224
233 INPUT:: 225 INPUT::
234 226
235 id : <id_for_response> 227 id : <id_for_response>
236 api_key : "<api_key>" 228 api_key : "<api_key>"
257 249
258 250
259 get_user 251 get_user
260 -------- 252 --------
261 253
262 Gets an user by username or user_id, Returns empty result if user is not found. 254 Get a user by username or userid. The result is empty if user can't be found.
263 If userid param is skipped it is set to id of user who is calling this method. 255 If userid param is skipped, it is set to id of user who is calling this method.
264 This command can be executed only using api_key belonging to user with admin 256 Any userid can be specified when the command is executed using the api_key of a user with admin rights.
265 rights, or regular users that cannot specify different userid than theirs 257 Regular users can only speicy their own userid.
266 258
267 259
268 INPUT:: 260 INPUT::
269 261
270 id : <id_for_response> 262 id : <id_for_response>
304 296
305 297
306 get_users 298 get_users
307 --------- 299 ---------
308 300
309 Lists all existing users. This command can be executed only using api_key 301 List all existing users.
310 belonging to user with admin rights. 302 This command can only be executed using the api_key of a user with admin rights.
311 303
312 304
313 INPUT:: 305 INPUT::
314 306
315 id : <id_for_response> 307 id : <id_for_response>
341 333
342 334
343 create_user 335 create_user
344 ----------- 336 -----------
345 337
346 Creates new user. This command can 338 Create new user.
347 be executed only using api_key belonging to user with admin rights. 339 This command can only be executed using the api_key of a user with admin rights.
348 340
349 341
350 INPUT:: 342 INPUT::
351 343
352 id : <id_for_response> 344 id : <id_for_response>
385 377
386 378
387 update_user 379 update_user
388 ----------- 380 -----------
389 381
390 updates given user if such user exists. This command can 382 Update the given user if such user exists.
391 be executed only using api_key belonging to user with admin rights. 383 This command can only be executed using the api_key of a user with admin rights.
392 384
393 385
394 INPUT:: 386 INPUT::
395 387
396 id : <id_for_response> 388 id : <id_for_response>
431 423
432 424
433 delete_user 425 delete_user
434 ----------- 426 -----------
435 427
436 428 Delete given user if such user exists.
437 deletes givenuser if such user exists. This command can 429 This command can only be executed using the api_key of a user with admin rights.
438 be executed only using api_key belonging to user with admin rights.
439 430
440 431
441 INPUT:: 432 INPUT::
442 433
443 id : <id_for_response> 434 id : <id_for_response>
458 449
459 450
460 get_user_group 451 get_user_group
461 -------------- 452 --------------
462 453
463 Gets an existing user group. This command can be executed only using api_key 454 Get an existing user group.
464 belonging to user with admin rights. 455 This command can only be executed using the api_key of a user with admin rights.
465 456
466 457
467 INPUT:: 458 INPUT::
468 459
469 id : <id_for_response> 460 id : <id_for_response>
502 493
503 494
504 get_user_groups 495 get_user_groups
505 --------------- 496 ---------------
506 497
507 Lists all existing user groups. This command can be executed only using 498 List all existing user groups.
508 api_key belonging to user with admin rights. 499 This command can only be executed using the api_key of a user with admin rights.
509 500
510 501
511 INPUT:: 502 INPUT::
512 503
513 id : <id_for_response> 504 id : <id_for_response>
530 521
531 522
532 create_user_group 523 create_user_group
533 ----------------- 524 -----------------
534 525
535 Creates new user group. This command can be executed only using api_key 526 Create a new user group.
536 belonging to user with admin rights 527 This command can only be executed using the api_key of a user with admin rights.
537 528
538 529
539 INPUT:: 530 INPUT::
540 531
541 id : <id_for_response> 532 id : <id_for_response>
562 553
563 554
564 add_user_to_user_group 555 add_user_to_user_group
565 ---------------------- 556 ----------------------
566 557
567 Adds a user to a user group. If user exists in that group success will be 558 Addsa user to a user group. If the user already is in that group, success will be
568 `false`. This command can be executed only using api_key 559 `false`.
569 belonging to user with admin rights 560 This command can only be executed using the api_key of a user with admin rights.
570 561
571 562
572 INPUT:: 563 INPUT::
573 564
574 id : <id_for_response> 565 id : <id_for_response>
582 OUTPUT:: 573 OUTPUT::
583 574
584 id : <id_given_in_input> 575 id : <id_given_in_input>
585 result: { 576 result: {
586 "success": True|False # depends on if member is in group 577 "success": True|False # depends on if member is in group
587 "msg": "added member `<username>` to user group `<groupname>` | 578 "msg": "added member `<username>` to a user group `<groupname>` |
588 User is already in that group" 579 User is already in that group"
589 } 580 }
590 error: null 581 error: null
591 582
592 583
593 remove_user_from_user_group 584 remove_user_from_user_group
594 --------------------------- 585 ---------------------------
595 586
596 Removes a user from a user group. If user is not in given group success will 587 Remove a user from a user group. If the user isn't in the given group, success will
597 be `false`. This command can be executed only 588 be `false`.
598 using api_key belonging to user with admin rights 589 This command can only be executed using the api_key of a user with admin rights.
599 590
600 591
601 INPUT:: 592 INPUT::
602 593
603 id : <id_for_response> 594 id : <id_for_response>
620 611
621 612
622 get_repo 613 get_repo
623 -------- 614 --------
624 615
625 Gets an existing repository by it's name or repository_id. Members will return 616 Get an existing repository by its name or repository_id. Members will contain
626 either users_group or user associated to that repository. This command can be 617 either users_group or user associated to that repository.
627 executed only using api_key belonging to user with admin 618 This command can only be executed using the api_key of a user with admin rights,
628 rights or regular user that have at least read access to repository. 619 or that of a regular user with at least read access to the repository.
629
630 620
631 INPUT:: 621 INPUT::
632 622
633 id : <id_for_response> 623 id : <id_for_response>
634 api_key : "<api_key>" 624 api_key : "<api_key>"
711 701
712 702
713 get_repos 703 get_repos
714 --------- 704 ---------
715 705
716 Lists all existing repositories. This command can be executed only using 706 List all existing repositories.
717 api_key belonging to user with admin rights or regular user that have 707 This command can only be executed using the api_key of a user with admin rights,
718 admin, write or read access to repository. 708 or that of a regular user with at least read access to the repository.
719 709
720 710
721 INPUT:: 711 INPUT::
722 712
723 id : <id_for_response> 713 id : <id_for_response>
750 740
751 741
752 get_repo_nodes 742 get_repo_nodes
753 -------------- 743 --------------
754 744
755 returns a list of nodes and it's children in a flat list for a given path 745 Return a list of files and directories for a given path at the given revision.
756 at given revision. It's possible to specify ret_type to show only `files` or 746 It's possible to specify ret_type to show only `files` or `dirs`.
757 `dirs`. This command can be executed only using api_key belonging to user 747 This command can only be executed using the api_key of a user with admin rights.
758 with admin rights
759 748
760 749
761 INPUT:: 750 INPUT::
762 751
763 id : <id_for_response> 752 id : <id_for_response>
784 773
785 774
786 create_repo 775 create_repo
787 ----------- 776 -----------
788 777
789 Creates a repository. If repository name contains "/", all needed repository 778 Create a repository. If repository name contains "/", all needed repository
790 groups will be created. For example "foo/bar/baz" will create groups 779 groups will be created. For example "foo/bar/baz" will create repository groups
791 "foo", "bar" (with "foo" as parent), and create "baz" repository with 780 "foo", "bar" (with "foo" as parent), and create "baz" repository with
792 "bar" as group. This command can be executed only using api_key belonging to user with admin 781 "bar" as group.
793 rights or regular user that have create repository permission. Regular users 782 This command can only be executed using the api_key of a user with admin rights,
794 cannot specify owner parameter 783 or that of a regular user with create repository permission.
784 Regular users cannot specify owner parameter.
795 785
796 786
797 INPUT:: 787 INPUT::
798 788
799 id : <id_for_response> 789 id : <id_for_response>
837 827
838 828
839 fork_repo 829 fork_repo
840 --------- 830 ---------
841 831
842 Creates a fork of given repo. In case of using celery this will 832 Create a fork of given repo. If using celery, this will
843 immidiatelly return success message, while fork is going to be created 833 return success message immidiatelly and fork will be created
844 asynchronous. This command can be executed only using api_key belonging to 834 asynchronously.
845 user with admin rights or regular user that have fork permission, and at least 835 This command can only be executed using the api_key of a user with admin rights,
846 read access to forking repository. Regular users cannot specify owner parameter. 836 or that of a regular user with fork permission and at least read access to the repository.
837 Regular users cannot specify owner parameter.
847 838
848 839
849 INPUT:: 840 INPUT::
850 841
851 id : <id_for_response> 842 id : <id_for_response>
873 864
874 865
875 delete_repo 866 delete_repo
876 ----------- 867 -----------
877 868
878 Deletes a repository. This command can be executed only using api_key belonging 869 Delete a repository.
879 to user with admin rights or regular user that have admin access to repository. 870 This command can only be executed using the api_key of a user with admin rights,
880 When `forks` param is set it's possible to detach or delete forks of deleting 871 or that of a regular user with admin access to the repository.
881 repository 872 When `forks` param is set it's possible to detach or delete forks of the deleted repository.
882 873
883 874
884 INPUT:: 875 INPUT::
885 876
886 id : <id_for_response> 877 id : <id_for_response>
902 893
903 894
904 grant_user_permission 895 grant_user_permission
905 --------------------- 896 ---------------------
906 897
907 Grant permission for user on given repository, or update existing one 898 Grant permission for user on given repository, or update existing one if found.
908 if found. This command can be executed only using api_key belonging to user 899 This command can only be executed using the api_key of a user with admin rights.
909 with admin rights.
910 900
911 901
912 INPUT:: 902 INPUT::
913 903
914 id : <id_for_response> 904 id : <id_for_response>
931 921
932 922
933 revoke_user_permission 923 revoke_user_permission
934 ---------------------- 924 ----------------------
935 925
936 Revoke permission for user on given repository. This command can be executed 926 Revoke permission for user on given repository.
937 only using api_key belonging to user with admin rights. 927 This command can only be executed using the api_key of a user with admin rights.
938 928
939 929
940 INPUT:: 930 INPUT::
941 931
942 id : <id_for_response> 932 id : <id_for_response>
959 949
960 grant_user_group_permission 950 grant_user_group_permission
961 --------------------------- 951 ---------------------------
962 952
963 Grant permission for user group on given repository, or update 953 Grant permission for user group on given repository, or update
964 existing one if found. This command can be executed only using 954 existing one if found.
965 api_key belonging to user with admin rights. 955 This command can only be executed using the api_key of a user with admin rights.
966 956
967 957
968 INPUT:: 958 INPUT::
969 959
970 id : <id_for_response> 960 id : <id_for_response>
987 977
988 978
989 revoke_user_group_permission 979 revoke_user_group_permission
990 ---------------------------- 980 ----------------------------
991 981
992 Revoke permission for user group on given repository.This command can be 982 Revoke permission for user group on given repository.
993 executed only using api_key belonging to user with admin rights. 983 This command can only be executed using the api_key of a user with admin rights.
994 984
995 INPUT:: 985 INPUT::
996 986
997 id : <id_for_response> 987 id : <id_for_response>
998 api_key : "<api_key>" 988 api_key : "<api_key>"