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