Mercurial > kallithea
annotate docs/api/api.rst @ 1500:256e729a94cd beta
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 |
| 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 |
|
1491
e63a2841714d
API docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
1447
diff
changeset
|
10 with JSON protocol both ways. An url to send API request in RhodeCode is |
| 1500 | 11 <your_server>/_admin/api |
| 1446 | 12 |
| 13 | |
| 1500 | 14 All clients need to send JSON data in such format:: |
| 1446 | 15 |
| 16 { | |
| 17 "api_key":"<api_key>", | |
| 18 "method":"<method_name>", | |
| 19 "args":{"<arg_key>":"<arg_val>"} | |
| 20 } | |
| 21 | |
| 1500 | 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 | |
| 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 | |
| 1446 | 29 |
| 30 .. note:: | |
| 31 | |
| 32 api_key can be found in your user account page | |
| 33 | |
| 34 | |
| 1500 | 35 RhodeCode API will return always a JSON formatted answer:: |
| 1446 | 36 |
| 37 { | |
| 38 "result": "<result>", | |
| 39 "error": null | |
| 40 } | |
| 41 | |
| 42 All responses from API will be `HTTP/1.0 200 OK`, if there's an error while | |
| 1500 | 43 calling api *error* key from response will contain failure description |
| 1446 | 44 and result will be null. |
| 45 | |
| 46 API METHODS | |
| 47 +++++++++++ | |
| 48 | |
| 49 | |
| 50 pull | |
| 51 ---- | |
| 52 | |
| 1447 | 53 Pulls given repo from remote location. Can be used to automatically keep |
| 1500 | 54 remote repos up to date. This command can be executed only using api_key |
| 55 belonging to user with admin rights | |
| 1446 | 56 |
| 1500 | 57 INPUT:: |
| 58 | |
|
1491
e63a2841714d
API docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
1447
diff
changeset
|
59 api_key:"<api_key>" |
| 1446 | 60 method: "pull" |
| 61 args: {"repo":<repo_name>} | |
| 62 | |
| 1500 | 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 |