Mercurial > kallithea

comparison docs/api/api.rst @ 1500:256e729a94cd beta

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Extended API - updated docs - created two new methods for creating users and creating users groups - changed user attribute generated from api_key to apiuser for better name compatibility with functoin parameters
author Marcin Kuzminski <marcin@python-works.com>
date Fri, 30 Sep 2011 18:03:20 +0300
parents e63a2841714d
children 8628c8706bf8
comparison
equal deleted inserted replaced
1499:182f5bd3b49d 1500:256e729a94cd
4 API 4 API
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 one 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 in RhodeCode is
11 <your-server>/_admin/api 11 <your_server>/_admin/api
12 12
13 13
14 Clients need to send JSON data in such format:: 14 All clients need to send JSON data in such format::
15 15
16 { 16 {
17 "api_key":"<api_key>", 17 "api_key":"<api_key>",
18 "method":"<method_name>", 18 "method":"<method_name>",
19 "args":{"<arg_key>":"<arg_val>"} 19 "args":{"<arg_key>":"<arg_val>"}
20 } 20 }
21 21
22 Simply provide api_key for access and permission validation 22 Example call for autopulling remotes repos using curl::
23 method is name of method to call 23 curl https://server.com/_admin/api -X POST -H 'content-type:text/plain' --data-binary '{"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}'
24 and args is an key:value list of arguments to pass to method 24
25 Simply provide
26 - *api_key* for access and permission validation.
27 - *method* is name of method to call
28 - *args* is an key:value list of arguments to pass to method
25 29
26 .. note:: 30 .. note::
27 31
28 api_key can be found in your user account page 32 api_key can be found in your user account page
29 33
30 34
31 And will receive JSON formatted answer:: 35 RhodeCode API will return always a JSON formatted answer::
32 36
33 { 37 {
34 "result": "<result>", 38 "result": "<result>",
35 "error": null 39 "error": null
36 } 40 }
37 41
38 All responses from API will be `HTTP/1.0 200 OK`, if there's an error while 42 All responses from API will be `HTTP/1.0 200 OK`, if there's an error while
39 calling api **error** key from response will contain failure description 43 calling api *error* key from response will contain failure description
40 and result will be null. 44 and result will be null.
41 45
42 API METHODS 46 API METHODS
43 +++++++++++ 47 +++++++++++
44 48
45 49
46 pull 50 pull
47 ---- 51 ----
48 52
49 Pulls given repo from remote location. Can be used to automatically keep 53 Pulls given repo from remote location. Can be used to automatically keep
50 remote repos upto date. This command can be executed only using admin users 54 remote repos up to date. This command can be executed only using api_key
51 api_key 55 belonging to user with admin rights
52 56
53 :: 57 INPUT::
58
54 api_key:"<api_key>" 59 api_key:"<api_key>"
55 method: "pull" 60 method: "pull"
56 args: {"repo":<repo_name>} 61 args: {"repo":<repo_name>}
57 62
63 OUTPUT::
64
65 result:"Pulled from <repo_name>"
66 error:null
67
68
69 create_user
70 -----------
71
72 Creates new user in RhodeCode. This command can be executed only using api_key
73 belonging to user with admin rights
74
75 INPUT::
76
77 api_key:"<api_key>"
78 method: "create_user"
79 args: {"username": "<username>",
80 "password": "<password>",
81 "active": "<bool>",
82 "admin": "<bool>",
83 "name": "<firstname>",
84 "lastname": "<lastname>",
85 "email": "<useremail>"}
86
87 OUTPUT::
88
89 result:{"id": <newuserid>,
90 "msg":"created new user <username>"}
91 error:null
92
93
94 create_users_group
95 ------------------
96
97 creates new users group. This command can be executed only using api_key
98 belonging to user with admin rights
99
100 INPUT::
101
102 api_key:"<api_key>"
103 method: "create_user"
104 args: {"name": "<groupname>",
105 "active":"<bool>"}
106
107 OUTPUT::
108
109 result:{"id": <newusersgroupid>,
110 "msg":"created new users group <groupname>"}
111 error:null