Mercurial > public > src > rhodecode
annotate docs/api/api.rst @ 1896:320dec24fb9a beta
Added instruction on enabling the API access to web views
author | Marcin Kuzminski <marcin@python-works.com> |
---|---|
date | Wed, 28 Dec 2011 23:57:57 +0200 |
parents | 203af05539e0 |
children | 9da24750f563 |
rev | line source |
---|---|
1526 | 1 .. _api: |
2 | |
3 | |
4 API | |
5 === | |
6 | |
7 | |
8 Starting from RhodeCode version 1.2 a simple API was implemented. | |
1580 | 9 There's a single schema for calling all api methods. API is implemented |
1676 | 10 with JSON protocol both ways. An url to send API request in RhodeCode is |
1580 | 11 <your_server>/_admin/api |
1526 | 12 |
13 | |
1896
320dec24fb9a
Added instruction on enabling the API access to web views
Marcin Kuzminski <marcin@python-works.com>
parents:
1895
diff
changeset
|
14 API access can also be turned on for each view decorated with `@LoginRequired` |
320dec24fb9a
Added instruction on enabling the API access to web views
Marcin Kuzminski <marcin@python-works.com>
parents:
1895
diff
changeset
|
15 decorator. To enable API access simple change standard login decorator into |
320dec24fb9a
Added instruction on enabling the API access to web views
Marcin Kuzminski <marcin@python-works.com>
parents:
1895
diff
changeset
|
16 `@LoginRequired(api_access=True)`. After such a change view can be accessed |
320dec24fb9a
Added instruction on enabling the API access to web views
Marcin Kuzminski <marcin@python-works.com>
parents:
1895
diff
changeset
|
17 by adding a GET parameter to url `?api_key=<api_key>`. By default it's only |
320dec24fb9a
Added instruction on enabling the API access to web views
Marcin Kuzminski <marcin@python-works.com>
parents:
1895
diff
changeset
|
18 enabled on RSS/ATOM feed views. |
320dec24fb9a
Added instruction on enabling the API access to web views
Marcin Kuzminski <marcin@python-works.com>
parents:
1895
diff
changeset
|
19 |
320dec24fb9a
Added instruction on enabling the API access to web views
Marcin Kuzminski <marcin@python-works.com>
parents:
1895
diff
changeset
|
20 |
1793
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
21 All clients are required to send JSON-RPC spec JSON data:: |
1526 | 22 |
1793
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
23 { |
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
24 "id:<id>, |
1526 | 25 "api_key":"<api_key>", |
26 "method":"<method_name>", | |
27 "args":{"<arg_key>":"<arg_val>"} | |
28 } | |
29 | |
1580 | 30 Example call for autopulling remotes repos using curl:: |
1793
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
31 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"}}' |
1580 | 32 |
1676 | 33 Simply provide |
1793
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
34 - *id* A value of any type, which is used to match the response with the request that it is replying to. |
1580 | 35 - *api_key* for access and permission validation. |
36 - *method* is name of method to call | |
37 - *args* is an key:value list of arguments to pass to method | |
1676 | 38 |
1526 | 39 .. note:: |
1676 | 40 |
41 api_key can be found in your user account page | |
42 | |
43 | |
1793
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
44 RhodeCode API will return always a JSON-RPC response:: |
1676 | 45 |
1793
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
46 { |
fee9895fa46e
changed API to match fully JSON-RPC specs
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
47 "id":<id>, |
1676 | 48 "result": "<result>", |
1526 | 49 "error": null |
50 } | |
51 | |
52 All responses from API will be `HTTP/1.0 200 OK`, if there's an error while | |
1676 | 53 calling api *error* key from response will contain failure description |
1526 | 54 and result will be null. |
55 | |
56 API METHODS | |
57 +++++++++++ | |
58 | |
1676 | 59 |
1526 | 60 pull |
61 ---- | |
62 | |
1676 | 63 Pulls given repo from remote location. Can be used to automatically keep |
64 remote repos up to date. This command can be executed only using api_key | |
1580 | 65 belonging to user with admin rights |
66 | |
67 INPUT:: | |
68 | |
1676 | 69 api_key : "<api_key>" |
70 method : "pull" | |
71 args : { | |
72 "repo" : "<repo_name>" | |
73 } | |
74 | |
75 OUTPUT:: | |
76 | |
77 result : "Pulled from <repo_name>" | |
78 error : null | |
79 | |
80 | |
81 get_users | |
82 --------- | |
83 | |
84 Lists all existing users. This command can be executed only using api_key | |
85 belonging to user with admin rights. | |
86 | |
87 INPUT:: | |
88 | |
89 api_key : "<api_key>" | |
90 method : "get_users" | |
91 args : { } | |
92 | |
93 OUTPUT:: | |
94 | |
95 result: [ | |
96 { | |
97 "id" : "<id>", | |
98 "username" : "<username>", | |
99 "firstname": "<firstname>", | |
100 "lastname" : "<lastname>", | |
101 "email" : "<email>", | |
102 "active" : "<bool>", | |
103 "admin" : "<bool>", | |
104 "ldap" : "<ldap_dn>" | |
105 }, | |
106 … | |
107 ] | |
108 error: null | |
109 | |
110 create_user | |
111 ----------- | |
112 | |
113 Creates new user in RhodeCode. This command can be executed only using api_key | |
114 belonging to user with admin rights. | |
115 | |
116 INPUT:: | |
117 | |
118 api_key : "<api_key>" | |
119 method : "create_user" | |
120 args : { | |
121 "username" : "<username>", | |
122 "password" : "<password>", | |
123 "firstname" : "<firstname>", | |
124 "lastname" : "<lastname>", | |
125 "email" : "<useremail>" | |
126 "active" : "<bool> = True", | |
127 "admin" : "<bool> = False", | |
128 "ldap_dn" : "<ldap_dn> = None" | |
129 } | |
1580 | 130 |
131 OUTPUT:: | |
132 | |
1676 | 133 result: { |
134 "msg" : "created new user <username>" | |
135 } | |
136 error: null | |
137 | |
138 get_users_groups | |
139 ---------------- | |
140 | |
141 Lists all existing users groups. This command can be executed only using api_key | |
142 belonging to user with admin rights. | |
143 | |
144 INPUT:: | |
145 | |
146 api_key : "<api_key>" | |
147 method : "get_users_groups" | |
148 args : { } | |
149 | |
150 OUTPUT:: | |
151 | |
152 result : [ | |
153 { | |
154 "id" : "<id>", | |
155 "name" : "<name>", | |
156 "active": "<bool>", | |
157 "members" : [ | |
158 { | |
159 "id" : "<userid>", | |
160 "username" : "<username>", | |
161 "firstname": "<firstname>", | |
162 "lastname" : "<lastname>", | |
163 "email" : "<email>", | |
164 "active" : "<bool>", | |
165 "admin" : "<bool>", | |
166 "ldap" : "<ldap_dn>" | |
167 }, | |
168 … | |
169 ] | |
170 } | |
171 ] | |
172 error : null | |
173 | |
174 get_users_group | |
175 --------------- | |
176 | |
177 Gets an existing users group. This command can be executed only using api_key | |
178 belonging to user with admin rights. | |
179 | |
180 INPUT:: | |
181 | |
182 api_key : "<api_key>" | |
183 method : "get_users_group" | |
184 args : { | |
185 "group_name" : "<name>" | |
186 } | |
187 | |
188 OUTPUT:: | |
189 | |
190 result : None if group not exist | |
191 { | |
192 "id" : "<id>", | |
193 "name" : "<name>", | |
194 "active": "<bool>", | |
195 "members" : [ | |
196 { "id" : "<userid>", | |
197 "username" : "<username>", | |
198 "firstname": "<firstname>", | |
199 "lastname" : "<lastname>", | |
200 "email" : "<email>", | |
201 "active" : "<bool>", | |
202 "admin" : "<bool>", | |
203 "ldap" : "<ldap_dn>" | |
204 }, | |
205 … | |
206 ] | |
207 } | |
208 error : null | |
209 | |
1580 | 210 create_users_group |
211 ------------------ | |
212 | |
1676 | 213 Creates new users group. This command can be executed only using api_key |
1580 | 214 belonging to user with admin rights |
215 | |
216 INPUT:: | |
217 | |
1676 | 218 api_key : "<api_key>" |
219 method : "create_users_group" | |
220 args: { | |
221 "name": "<name>", | |
222 "active":"<bool> = True" | |
223 } | |
224 | |
225 OUTPUT:: | |
226 | |
227 result: { | |
228 "id": "<newusersgroupid>", | |
229 "msg": "created new users group <name>" | |
230 } | |
231 error: null | |
232 | |
1878
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
233 add_user_to_users_group |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
234 ----------------------- |
1676 | 235 |
236 Adds a user to a users group. This command can be executed only using api_key | |
237 belonging to user with admin rights | |
238 | |
239 INPUT:: | |
240 | |
241 api_key : "<api_key>" | |
242 method : "add_user_users_group" | |
243 args: { | |
244 "group_name" : "<groupname>", | |
1895
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
245 "username" : "<username>" |
1676 | 246 } |
247 | |
248 OUTPUT:: | |
249 | |
250 result: { | |
251 "id": "<newusersgroupmemberid>", | |
252 "msg": "created new users group member" | |
253 } | |
254 error: null | |
255 | |
256 get_repos | |
257 --------- | |
258 | |
259 Lists all existing repositories. This command can be executed only using api_key | |
260 belonging to user with admin rights | |
261 | |
262 INPUT:: | |
263 | |
264 api_key : "<api_key>" | |
265 method : "get_repos" | |
266 args: { } | |
1580 | 267 |
268 OUTPUT:: | |
269 | |
1676 | 270 result: [ |
271 { | |
272 "id" : "<id>", | |
273 "name" : "<name>" | |
274 "type" : "<type>", | |
275 "description" : "<description>" | |
276 }, | |
277 … | |
278 ] | |
279 error: null | |
280 | |
281 get_repo | |
282 -------- | |
283 | |
284 Gets an existing repository. This command can be executed only using api_key | |
285 belonging to user with admin rights | |
286 | |
287 INPUT:: | |
288 | |
289 api_key : "<api_key>" | |
290 method : "get_repo" | |
291 args: { | |
292 "name" : "<name>" | |
293 } | |
294 | |
295 OUTPUT:: | |
296 | |
297 result: None if repository not exist | |
298 { | |
299 "id" : "<id>", | |
300 "name" : "<name>" | |
301 "type" : "<type>", | |
302 "description" : "<description>", | |
303 "members" : [ | |
304 { "id" : "<userid>", | |
305 "username" : "<username>", | |
306 "firstname": "<firstname>", | |
307 "lastname" : "<lastname>", | |
308 "email" : "<email>", | |
309 "active" : "<bool>", | |
310 "admin" : "<bool>", | |
311 "ldap" : "<ldap_dn>", | |
1878
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
312 "permission" : "repository.(read|write|admin)" |
1676 | 313 }, |
314 … | |
315 { | |
316 "id" : "<usersgroupid>", | |
317 "name" : "<usersgroupname>", | |
318 "active": "<bool>", | |
1878
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
319 "permission" : "repository.(read|write|admin)" |
1676 | 320 }, |
321 … | |
322 ] | |
323 } | |
324 error: null | |
325 | |
1895
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
326 get_repo_nodes |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
327 -------------- |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
328 |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
329 returns a list of nodes and it's children in a flat list for a given path |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
330 at given revision. It's possible to specify ret_type to show only files or |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
331 dirs. This command can be executed only using api_key belonging to user |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
332 with admin rights |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
333 |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
334 INPUT:: |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
335 |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
336 api_key : "<api_key>" |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
337 method : "get_repo_nodes" |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
338 args: { |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
339 "repo_name" : "<name>", |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
340 "revision" : "<revision>", |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
341 "root_path" : "<root_path>", |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
342 "ret_type" : "<ret_type>" = 'all' |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
343 } |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
344 |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
345 OUTPUT:: |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
346 |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
347 result: [ |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
348 { |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
349 "name" : "<name>" |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
350 "type" : "<type>", |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
351 }, |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
352 … |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
353 ] |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
354 error: null |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
355 |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
356 |
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
357 |
1676 | 358 create_repo |
359 ----------- | |
360 | |
361 Creates a repository. This command can be executed only using api_key | |
362 belonging to user with admin rights. | |
363 If repository name contains "/", all needed repository groups will be created. | |
364 For example "foo/bar/baz" will create groups "foo", "bar" (with "foo" as parent), | |
365 and create "baz" repository with "bar" as group. | |
366 | |
367 INPUT:: | |
368 | |
369 api_key : "<api_key>" | |
370 method : "create_repo" | |
371 args: { | |
372 "name" : "<name>", | |
373 "owner_name" : "<ownername>", | |
374 "description" : "<description> = ''", | |
375 "repo_type" : "<type> = 'hg'", | |
376 "private" : "<bool> = False" | |
377 } | |
378 | |
379 OUTPUT:: | |
380 | |
381 result: None | |
382 error: null | |
383 | |
384 add_user_to_repo | |
385 ---------------- | |
386 | |
387 Add a user to a repository. This command can be executed only using api_key | |
388 belonging to user with admin rights. | |
389 If "perm" is None, user will be removed from the repository. | |
390 | |
391 INPUT:: | |
392 | |
393 api_key : "<api_key>" | |
394 method : "add_user_to_repo" | |
395 args: { | |
396 "repo_name" : "<reponame>", | |
1895
203af05539e0
implements #330 api method for listing nodes at particular revision
Marcin Kuzminski <marcin@python-works.com>
parents:
1878
diff
changeset
|
397 "username" : "<username>", |
1878
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
398 "perm" : "(None|repository.(read|write|admin))", |
1676 | 399 } |
400 | |
401 OUTPUT:: | |
402 | |
403 result: None | |
404 error: null | |
1878
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
405 |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
406 add_users_group_to_repo |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
407 ----------------------- |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
408 |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
409 Add a users group to a repository. This command can be executed only using |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
410 api_key belonging to user with admin rights. If "perm" is None, group will |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
411 be removed from the repository. |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
412 |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
413 INPUT:: |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
414 |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
415 api_key : "<api_key>" |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
416 method : "add_users_group_to_repo" |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
417 args: { |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
418 "repo_name" : "<reponame>", |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
419 "group_name" : "<groupname>", |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
420 "perm" : "(None|repository.(read|write|admin))", |
631caf880b87
implements #329
Marcin Kuzminski <marcin@python-works.com>
parents:
1793
diff
changeset
|
421 } |