Mercurial > public > src > rhodecode
annotate docs/api/api.rst @ 1879:702e29ce1e9b
backporting #329 into stable
| author | Marcin Kuzminski <marcin@python-works.com> |
|---|---|
| date | Wed, 21 Dec 2011 02:05:31 +0200 |
| parents | 8628c8706bf8 |
| children | 466292e57bfd |
| 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 | |
|
1879
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
14 All clients are required to send JSON-RPC spec JSON data:: |
| 1526 | 15 |
| 16 { | |
| 17 "api_key":"<api_key>", | |
| 18 "method":"<method_name>", | |
| 19 "args":{"<arg_key>":"<arg_val>"} | |
| 20 } | |
| 21 | |
| 1580 | 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"}}' | |
| 24 | |
| 1676 | 25 Simply provide |
| 1580 | 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 | |
| 1676 | 29 |
| 1526 | 30 .. note:: |
| 1676 | 31 |
| 32 api_key can be found in your user account page | |
| 33 | |
| 34 | |
|
1879
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
35 RhodeCode API will return always a JSON-RPC response:: |
| 1676 | 36 |
| 1526 | 37 { |
| 1676 | 38 "result": "<result>", |
| 1526 | 39 "error": null |
| 40 } | |
| 41 | |
| 42 All responses from API will be `HTTP/1.0 200 OK`, if there's an error while | |
| 1676 | 43 calling api *error* key from response will contain failure description |
| 1526 | 44 and result will be null. |
| 45 | |
| 46 API METHODS | |
| 47 +++++++++++ | |
| 48 | |
| 1676 | 49 |
| 1526 | 50 pull |
| 51 ---- | |
| 52 | |
| 1676 | 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 | |
| 1580 | 55 belonging to user with admin rights |
| 56 | |
| 57 INPUT:: | |
| 58 | |
| 1676 | 59 api_key : "<api_key>" |
| 60 method : "pull" | |
| 61 args : { | |
| 62 "repo" : "<repo_name>" | |
| 63 } | |
| 64 | |
| 65 OUTPUT:: | |
| 66 | |
| 67 result : "Pulled from <repo_name>" | |
| 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 | |
| 100 create_user | |
| 101 ----------- | |
| 102 | |
| 103 Creates new user in RhodeCode. This command can be executed only using api_key | |
| 104 belonging to user with admin rights. | |
| 105 | |
| 106 INPUT:: | |
| 107 | |
| 108 api_key : "<api_key>" | |
| 109 method : "create_user" | |
| 110 args : { | |
| 111 "username" : "<username>", | |
| 112 "password" : "<password>", | |
| 113 "firstname" : "<firstname>", | |
| 114 "lastname" : "<lastname>", | |
| 115 "email" : "<useremail>" | |
| 116 "active" : "<bool> = True", | |
| 117 "admin" : "<bool> = False", | |
| 118 "ldap_dn" : "<ldap_dn> = None" | |
| 119 } | |
| 1580 | 120 |
| 121 OUTPUT:: | |
| 122 | |
| 1676 | 123 result: { |
| 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 | |
| 1580 | 200 create_users_group |
| 201 ------------------ | |
| 202 | |
| 1676 | 203 Creates new users group. This command can be executed only using api_key |
| 1580 | 204 belonging to user with admin rights |
| 205 | |
| 206 INPUT:: | |
| 207 | |
| 1676 | 208 api_key : "<api_key>" |
| 209 method : "create_users_group" | |
| 210 args: { | |
| 211 "name": "<name>", | |
| 212 "active":"<bool> = True" | |
| 213 } | |
| 214 | |
| 215 OUTPUT:: | |
| 216 | |
| 217 result: { | |
| 218 "id": "<newusersgroupid>", | |
| 219 "msg": "created new users group <name>" | |
| 220 } | |
| 221 error: null | |
| 222 | |
|
1879
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
223 add_user_to_users_group |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
224 ----------------------- |
| 1676 | 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: { } | |
| 1580 | 257 |
| 258 OUTPUT:: | |
| 259 | |
| 1676 | 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>", | |
|
1879
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
302 "permission" : "repository.(read|write|admin)" |
| 1676 | 303 }, |
| 304 … | |
| 305 { | |
| 306 "id" : "<usersgroupid>", | |
| 307 "name" : "<usersgroupname>", | |
| 308 "active": "<bool>", | |
|
1879
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
309 "permission" : "repository.(read|write|admin)" |
| 1676 | 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>", | |
|
1879
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
356 "perm" : "(None|repository.(read|write|admin))", |
| 1676 | 357 } |
| 358 | |
| 359 OUTPUT:: | |
| 360 | |
| 361 result: None | |
| 362 error: null | |
|
1879
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
363 |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
364 add_users_group_to_repo |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
365 ----------------------- |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
366 |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
367 Add a users group to a repository. This command can be executed only using |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
368 api_key belonging to user with admin rights. If "perm" is None, group will |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
369 be removed from the repository. |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
370 |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
371 INPUT:: |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
372 |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
373 api_key : "<api_key>" |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
374 method : "add_users_group_to_repo" |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
375 args: { |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
376 "repo_name" : "<reponame>", |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
377 "group_name" : "<groupname>", |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
378 "perm" : "(None|repository.(read|write|admin))", |
|
702e29ce1e9b
backporting #329 into stable
Marcin Kuzminski <marcin@python-works.com>
parents:
1676
diff
changeset
|
379 } |