Mercurial > kallithea

comparison docs/api/api.rst @ 1592:8628c8706bf8 beta

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[API] Update doc
author Nicolas VINOT <aeris@imirhil.fr>
date Sat, 22 Oct 2011 23:18:03 +0200
parents 256e729a94cd
children fee9895fa46e 702e29ce1e9b
comparison
equal deleted inserted replaced
1591:0b63a0d2cede 1592:8628c8706bf8
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 in RhodeCode is
11 <your_server>/_admin/api 11 <your_server>/_admin/api
12 12
13 13
14 All clients need to send JSON data in such format:: 14 All clients need to send JSON data in such format::
15 15
20 } 20 }
21 21
22 Example call for autopulling remotes repos using curl:: 22 Example call for autopulling remotes repos using curl::
23 curl https://server.com/_admin/api -X POST -H 'content-type:text/plain' --data-binary '{"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}' 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 24
25 Simply provide 25 Simply provide
26 - *api_key* for access and permission validation. 26 - *api_key* for access and permission validation.
27 - *method* is name of method to call 27 - *method* is name of method to call
28 - *args* is an key:value list of arguments to pass to method 28 - *args* is an key:value list of arguments to pass to method
29 29
30 .. note:: 30 .. note::
31 31
32 api_key can be found in your user account page 32 api_key can be found in your user account page
33 33
34 34
35 RhodeCode API will return always a JSON formatted answer:: 35 RhodeCode API will return always a JSON formatted answer::
36 36
37 { 37 {
38 "result": "<result>", 38 "result": "<result>",
39 "error": null 39 "error": null
40 } 40 }
41 41
42 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
43 calling api *error* key from response will contain failure description 43 calling api *error* key from response will contain failure description
44 and result will be null. 44 and result will be null.
45 45
46 API METHODS 46 API METHODS
47 +++++++++++ 47 +++++++++++
48 48
49 49
50 pull 50 pull
51 ---- 51 ----
52 52
53 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
54 remote repos up to date. This command can be executed only using api_key 54 remote repos up to date. This command can be executed only using api_key
55 belonging to user with admin rights 55 belonging to user with admin rights
56 56
57 INPUT:: 57 INPUT::
58 58
59 api_key:"<api_key>" 59 api_key : "<api_key>"
60 method: "pull" 60 method : "pull"
61 args: {"repo":<repo_name>} 61 args : {
62 62 "repo" : "<repo_name>"
63 OUTPUT:: 63 }
64 64
65 result:"Pulled from <repo_name>" 65 OUTPUT::
66 error:null 66
67 67 result : "Pulled from <repo_name>"
68 68 error : null
69
70
71 get_users
72 ---------
73
74 Lists all existing users. This command can be executed only using api_key
75 belonging to user with admin rights.
76
77 INPUT::
78
79 api_key : "<api_key>"
80 method : "get_users"
81 args : { }
82
83 OUTPUT::
84
85 result: [
86 {
87 "id" : "<id>",
88 "username" : "<username>",
89 "firstname": "<firstname>",
90 "lastname" : "<lastname>",
91 "email" : "<email>",
92 "active" : "<bool>",
93 "admin" :  "<bool>",
94 "ldap" : "<ldap_dn>"
95 },
96 …
97 ]
98 error: null
99
69 create_user 100 create_user
70 ----------- 101 -----------
71 102
72 Creates new user in RhodeCode. This command can be executed only using api_key 103 Creates new user in RhodeCode. This command can be executed only using api_key
73 belonging to user with admin rights 104 belonging to user with admin rights.
74 105
75 INPUT:: 106 INPUT::
76 107
77 api_key:"<api_key>" 108 api_key : "<api_key>"
78 method: "create_user" 109 method : "create_user"
79 args: {"username": "<username>", 110 args : {
80 "password": "<password>", 111 "username" : "<username>",
81 "active": "<bool>", 112 "password" : "<password>",
82 "admin": "<bool>", 113 "firstname" : "<firstname>",
83 "name": "<firstname>", 114 "lastname" : "<lastname>",
84 "lastname": "<lastname>", 115 "email" : "<useremail>"
85 "email": "<useremail>"} 116 "active" : "<bool> = True",
86 117 "admin" : "<bool> = False",
87 OUTPUT:: 118 "ldap_dn" : "<ldap_dn> = None"
88 119 }
89 result:{"id": <newuserid>, 120
90 "msg":"created new user <username>"} 121 OUTPUT::
91 error:null 122
92 123 result: {
93 124 "msg" : "created new user <username>"
125 }
126 error: null
127
128 get_users_groups
129 ----------------
130
131 Lists all existing users groups. This command can be executed only using api_key
132 belonging to user with admin rights.
133
134 INPUT::
135
136 api_key : "<api_key>"
137 method : "get_users_groups"
138 args : { }
139
140 OUTPUT::
141
142 result : [
143 {
144 "id" : "<id>",
145 "name" : "<name>",
146 "active": "<bool>",
147 "members" : [
148 {
149 "id" : "<userid>",
150 "username" : "<username>",
151 "firstname": "<firstname>",
152 "lastname" : "<lastname>",
153 "email" : "<email>",
154 "active" : "<bool>",
155 "admin" :  "<bool>",
156 "ldap" : "<ldap_dn>"
157 },
158 …
159 ]
160 }
161 ]
162 error : null
163
164 get_users_group
165 ---------------
166
167 Gets an existing users group. This command can be executed only using api_key
168 belonging to user with admin rights.
169
170 INPUT::
171
172 api_key : "<api_key>"
173 method : "get_users_group"
174 args : {
175 "group_name" : "<name>"
176 }
177
178 OUTPUT::
179
180 result : None if group not exist
181 {
182 "id" : "<id>",
183 "name" : "<name>",
184 "active": "<bool>",
185 "members" : [
186 { "id" : "<userid>",
187 "username" : "<username>",
188 "firstname": "<firstname>",
189 "lastname" : "<lastname>",
190 "email" : "<email>",
191 "active" : "<bool>",
192 "admin" :  "<bool>",
193 "ldap" : "<ldap_dn>"
194 },
195 …
196 ]
197 }
198 error : null
199
94 create_users_group 200 create_users_group
95 ------------------ 201 ------------------
96 202
97 creates new users group. This command can be executed only using api_key 203 Creates new users group. This command can be executed only using api_key
98 belonging to user with admin rights 204 belonging to user with admin rights
99 205
100 INPUT:: 206 INPUT::
101 207
102 api_key:"<api_key>" 208 api_key : "<api_key>"
103 method: "create_user" 209 method : "create_users_group"
104 args: {"name": "<groupname>", 210 args: {
105 "active":"<bool>"} 211 "name": "<name>",
106 212 "active":"<bool> = True"
107 OUTPUT:: 213 }
108 214
109 result:{"id": <newusersgroupid>, 215 OUTPUT::
110 "msg":"created new users group <groupname>"} 216
111 error:null 217 result: {
218 "id": "<newusersgroupid>",
219 "msg": "created new users group <name>"
220 }
221 error: null
222
223 add_user_to_users_groups
224 ------------------------
225
226 Adds a user to a users group. This command can be executed only using api_key
227 belonging to user with admin rights
228
229 INPUT::
230
231 api_key : "<api_key>"
232 method : "add_user_users_group"
233 args: {
234 "group_name" : "<groupname>",
235 "user_name" : "<username>"
236 }
237
238 OUTPUT::
239
240 result: {
241 "id": "<newusersgroupmemberid>",
242 "msg": "created new users group member"
243 }
244 error: null
245
246 get_repos
247 ---------
248
249 Lists all existing repositories. This command can be executed only using api_key
250 belonging to user with admin rights
251
252 INPUT::
253
254 api_key : "<api_key>"
255 method : "get_repos"
256 args: { }
257
258 OUTPUT::
259
260 result: [
261 {
262 "id" : "<id>",
263 "name" : "<name>"
264 "type" : "<type>",
265 "description" : "<description>"
266 },
267 …
268 ]
269 error: null
270
271 get_repo
272 --------
273
274 Gets an existing repository. This command can be executed only using api_key
275 belonging to user with admin rights
276
277 INPUT::
278
279 api_key : "<api_key>"
280 method : "get_repo"
281 args: {
282 "name" : "<name>"
283 }
284
285 OUTPUT::
286
287 result: None if repository not exist
288 {
289 "id" : "<id>",
290 "name" : "<name>"
291 "type" : "<type>",
292 "description" : "<description>",
293 "members" : [
294 { "id" : "<userid>",
295 "username" : "<username>",
296 "firstname": "<firstname>",
297 "lastname" : "<lastname>",
298 "email" : "<email>",
299 "active" : "<bool>",
300 "admin" :  "<bool>",
301 "ldap" : "<ldap_dn>",
302 "permission" : "repository_(read|write|admin)"
303 },
304 …
305 {
306 "id" : "<usersgroupid>",
307 "name" : "<usersgroupname>",
308 "active": "<bool>",
309 "permission" : "repository_(read|write|admin)"
310 },
311 …
312 ]
313 }
314 error: null
315
316 create_repo
317 -----------
318
319 Creates a repository. This command can be executed only using api_key
320 belonging to user with admin rights.
321 If repository name contains "/", all needed repository groups will be created.
322 For example "foo/bar/baz" will create groups "foo", "bar" (with "foo" as parent),
323 and create "baz" repository with "bar" as group.
324
325 INPUT::
326
327 api_key : "<api_key>"
328 method : "create_repo"
329 args: {
330 "name" : "<name>",
331 "owner_name" : "<ownername>",
332 "description" : "<description> = ''",
333 "repo_type" : "<type> = 'hg'",
334 "private" : "<bool> = False"
335 }
336
337 OUTPUT::
338
339 result: None
340 error: null
341
342 add_user_to_repo
343 ----------------
344
345 Add a user to a repository. This command can be executed only using api_key
346 belonging to user with admin rights.
347 If "perm" is None, user will be removed from the repository.
348
349 INPUT::
350
351 api_key : "<api_key>"
352 method : "add_user_to_repo"
353 args: {
354 "repo_name" : "<reponame>",
355 "user_name" : "<username>",
356 "perm" : "(None|repository_(read|write|admin))",
357 }
358
359 OUTPUT::
360
361 result: None
362 error: null