Mercurial > public > src > rhodecode
diff docs/api/api.rst @ 2633:d80a68e2ebcc beta
return proper id from users_group
update api docs
| author | Marcin Kuzminski <marcin@python-works.com> |
|---|---|
| date | Sun, 01 Jul 2012 23:36:03 +0200 |
| parents | 374693af2849 |
| children | 4565e655ea2a |
line wrap: on
line diff
--- a/docs/api/api.rst Sun Jul 01 18:06:56 2012 +0200 +++ b/docs/api/api.rst Sun Jul 01 23:36:03 2012 +0200 @@ -7,7 +7,7 @@ Starting from RhodeCode version 1.2 a simple API was implemented. There's a single schema for calling all api methods. API is implemented -with JSON protocol both ways. An url to send API request in RhodeCode is +with JSON protocol both ways. An url to send API request to RhodeCode is <your_server>/_admin/api API ACCESS FOR WEB VIEWS @@ -63,7 +63,7 @@ API CLIENT ++++++++++ -From version 1.4 RhodeCode adds a binary script that allows to easily +From version 1.4 RhodeCode adds a script that allows to easily communicate with API. After installing RhodeCode a `rhodecode-api` script will be available. @@ -117,12 +117,13 @@ api_key : "<api_key>" method : "pull" args : { - "repo_name" : "<reponame>" + "repoid" : "<reponame or repo_id>" } OUTPUT:: - result : "Pulled from <reponame>" + id : <id_given_in_input> + result : "Pulled from `<reponame>`" error : null @@ -145,9 +146,10 @@ OUTPUT:: + id : <id_given_in_input> result: None if user does not exist or { - "id" : "<id>", + "user_id" : "<user_id>", "username" : "<username>", "firstname": "<firstname>", "lastname" : "<lastname>", @@ -185,13 +187,15 @@ OUTPUT:: + id : <id_given_in_input> result: [ { - "id" : "<id>", + "user_id" : "<user_id>", "username" : "<username>", "firstname": "<firstname>", "lastname" : "<lastname>", "email" : "<email>", + "emails": "<list_of_all_additional_emails>", "active" : "<bool>", "admin" : "<bool>", "ldap_dn" : "<ldap_dn>", @@ -216,26 +220,27 @@ method : "create_user" args : { "username" : "<username>", + "email" : "<useremail>", "password" : "<password>", - "email" : "<useremail>", - "firstname" : "<firstname> = None", - "lastname" : "<lastname> = None", - "active" : "<bool> = True", - "admin" : "<bool> = False", - "ldap_dn" : "<ldap_dn> = None" + "firstname" : "<firstname> = Optional(None)", + "lastname" : "<lastname> = Optional(None)", + "active" : "<bool> = Optional(True)", + "admin" : "<bool> = Optional(False)", + "ldap_dn" : "<ldap_dn> = Optional(None)" } OUTPUT:: + id : <id_given_in_input> result: { - "id" : "<new_user_id>", - "msg" : "created new user <username>", + "msg" : "created new user `<username>`", "user": { - "id" : "<id>", + "user_id" : "<user_id>", "username" : "<username>", "firstname": "<firstname>", "lastname" : "<lastname>", "email" : "<email>", + "emails": "<list_of_all_additional_emails>", "active" : "<bool>", "admin" : "<bool>", "ldap_dn" : "<ldap_dn>", @@ -259,27 +264,28 @@ method : "update_user" args : { "userid" : "<user_id or username>", - "username" : "<username>", - "password" : "<password>", - "email" : "<useremail>", - "firstname" : "<firstname>", - "lastname" : "<lastname>", - "active" : "<bool>", - "admin" : "<bool>", - "ldap_dn" : "<ldap_dn>" + "username" : "<username> = Optional", + "email" : "<useremail> = Optional", + "password" : "<password> = Optional", + "firstname" : "<firstname> = Optional", + "lastname" : "<lastname> = Optional", + "active" : "<bool> = Optional", + "admin" : "<bool> = Optional", + "ldap_dn" : "<ldap_dn> = Optional" } OUTPUT:: + id : <id_given_in_input> result: { - "id" : "<edited_user_id>", "msg" : "updated user ID:<userid> <username>", "user": { - "id" : "<id>", + "user_id" : "<user_id>", "username" : "<username>", "firstname": "<firstname>", "lastname" : "<lastname>", "email" : "<email>", + "emails": "<list_of_all_additional_emails>", "active" : "<bool>", "admin" : "<bool>", "ldap_dn" : "<ldap_dn>", @@ -308,9 +314,10 @@ OUTPUT:: + id : <id_given_in_input> result: { - "id" : "<edited_user_id>", - "msg" : "deleted user ID:<userid> <username>" + "msg" : "deleted user ID:<userid> <username>", + "user": null } error: null @@ -328,25 +335,29 @@ api_key : "<api_key>" method : "get_users_group" args : { - "group_name" : "<name>" + "usersgroupid" : "<users group id or name>" } OUTPUT:: + id : <id_given_in_input> result : None if group not exist { - "id" : "<id>", - "group_name" : "<groupname>", - "active": "<bool>", + "users_group_id" : "<id>", + "group_name" : "<groupname>", + "active": "<bool>", "members" : [ - { "id" : "<userid>", + { + "user_id" : "<user_id>", "username" : "<username>", "firstname": "<firstname>", "lastname" : "<lastname>", "email" : "<email>", + "emails": "<list_of_all_additional_emails>", "active" : "<bool>", "admin" : "<bool>", - "ldap" : "<ldap_dn>" + "ldap_dn" : "<ldap_dn>", + "last_login": "<last_login>", }, … ] @@ -370,25 +381,29 @@ OUTPUT:: + id : <id_given_in_input> result : [ { - "id" : "<id>", - "group_name" : "<groupname>", - "active": "<bool>", - "members" : [ - { - "id" : "<userid>", - "username" : "<username>", - "firstname": "<firstname>", - "lastname" : "<lastname>", - "email" : "<email>", - "active" : "<bool>", - "admin" : "<bool>", - "ldap" : "<ldap_dn>" - }, - … - ] - } + "users_group_id" : "<id>", + "group_name" : "<groupname>", + "active": "<bool>", + "members" : [ + { + "user_id" : "<user_id>", + "username" : "<username>", + "firstname": "<firstname>", + "lastname" : "<lastname>", + "email" : "<email>", + "emails": "<list_of_all_additional_emails>", + "active" : "<bool>", + "admin" : "<bool>", + "ldap_dn" : "<ldap_dn>", + "last_login": "<last_login>", + }, + … + ] + }, + … ] error : null @@ -407,14 +422,34 @@ method : "create_users_group" args: { "group_name": "<groupname>", - "active":"<bool> = True" + "active":"<bool> = Optional(True)" } OUTPUT:: + id : <id_given_in_input> result: { - "id": "<newusersgroupid>", - "msg": "created new users group <groupname>" + "msg": "created new users group `<groupname>`", + "users_group": { + "users_group_id" : "<id>", + "group_name" : "<groupname>", + "active": "<bool>", + "members" : [ + { + "user_id" : "<user_id>", + "username" : "<username>", + "firstname": "<firstname>", + "lastname" : "<lastname>", + "email" : "<email>", + "emails": "<list_of_all_additional_emails>", + "active" : "<bool>", + "admin" : "<bool>", + "ldap_dn" : "<ldap_dn>", + "last_login": "<last_login>", + }, + … + ] + }, } error: null @@ -433,16 +468,16 @@ api_key : "<api_key>" method : "add_user_users_group" args: { - "group_name" : "<groupname>", - "username" : "<username>" + "usersgroupid" : "<users group id or name>", + "userid" : "<user_id or username>", } OUTPUT:: + id : <id_given_in_input> result: { - "id": "<newusersgroupmemberid>", "success": True|False # depends on if member is in group - "msg": "added member <username> to users group <groupname> | + "msg": "added member `<username>` to users group `<groupname>` | User is already in that group" } error: null @@ -462,12 +497,13 @@ api_key : "<api_key>" method : "remove_user_from_users_group" args: { - "group_name" : "<groupname>", - "username" : "<username>" + "usersgroupid" : "<users group id or name>", + "userid" : "<user_id or username>", } OUTPUT:: + id : <id_given_in_input> result: { "success": True|False, # depends on if member is in group "msg": "removed member <username> from users group <groupname> | @@ -495,26 +531,32 @@ OUTPUT:: + id : <id_given_in_input> result: None if repository does not exist or { - "id" : "<id>", + "repo_id" : "<repo_id>", "repo_name" : "<reponame>" - "type" : "<type>", - "description" : "<description>", + "repo_type" : "<repo_type>", "clone_uri" : "<clone_uri>", "private": : "<bool>", - "created_on" : "<datetimecreated>", + "created_on" : "<datetimecreated>", + "description" : "<description>", + "landing_rev": "<landing_rev>", + "owner": "<repo_owner>", + "fork_of": "<name_of_fork_parent>", "members" : [ { "type": "user", - "id" : "<userid>", - "username" : "<username>", - "firstname": "<firstname>", - "lastname" : "<lastname>", - "email" : "<email>", - "active" : "<bool>", - "admin" : "<bool>", - "ldap" : "<ldap_dn>", + "user_id" : "<user_id>", + "username" : "<username>", + "firstname": "<firstname>", + "lastname" : "<lastname>", + "email" : "<email>", + "emails": "<list_of_all_additional_emails>", + "active" : "<bool>", + "admin" : "<bool>", + "ldap_dn" : "<ldap_dn>", + "last_login": "<last_login>", "permission" : "repository.(read|write|admin)" }, … @@ -547,15 +589,19 @@ OUTPUT:: + id : <id_given_in_input> result: [ { - "id" : "<id>", + "repo_id" : "<repo_id>", "repo_name" : "<reponame>" - "type" : "<type>", - "description" : "<description>", + "repo_type" : "<repo_type>", "clone_uri" : "<clone_uri>", "private": : "<bool>", - "created_on" : "<datetimecreated>", + "created_on" : "<datetimecreated>", + "description" : "<description>", + "landing_rev": "<landing_rev>", + "owner": "<repo_owner>", + "fork_of": "<name_of_fork_parent>", }, … ] @@ -577,14 +623,15 @@ api_key : "<api_key>" method : "get_repo_nodes" args: { - "repo_name" : "<reponame>", + "repoid" : "<reponame or repo_id>" "revision" : "<revision>", "root_path" : "<root_path>", - "ret_type" : "<ret_type>" = 'all' + "ret_type" : "<ret_type> = Optional('all')" } OUTPUT:: + id : <id_given_in_input> result: [ { "name" : "<name>" @@ -612,26 +659,30 @@ method : "create_repo" args: { "repo_name" : "<reponame>", - "owner_name" : "<ownername>", - "description" : "<description> = ''", - "repo_type" : "<type> = 'hg'", - "private" : "<bool> = False", - "clone_uri" : "<clone_uri> = None", + "owner" : "<onwer_name_or_id>", + "repo_type" : "<repo_type>", + "description" : "<description> = Optional('')", + "private" : "<bool> = Optional(False)", + "clone_uri" : "<clone_uri> = Optional(None)", + "landing_rev" : "<landing_rev> = Optional('tip')", } OUTPUT:: + id : <id_given_in_input> result: { - "id": "<newrepoid>", - "msg": "Created new repository <reponame>", + "msg": "Created new repository `<reponame>`", "repo": { - "id" : "<id>", + "repo_id" : "<repo_id>", "repo_name" : "<reponame>" - "type" : "<type>", - "description" : "<description>", + "repo_type" : "<repo_type>", "clone_uri" : "<clone_uri>", "private": : "<bool>", - "created_on" : "<datetimecreated>", + "created_on" : "<datetimecreated>", + "description" : "<description>", + "landing_rev": "<landing_rev>", + "owner": "<repo_owner>", + "fork_of": "<name_of_fork_parent>", }, } error: null @@ -650,13 +701,15 @@ api_key : "<api_key>" method : "delete_repo" args: { - "repo_name" : "<reponame>", + "repoid" : "<reponame or repo_id>" } OUTPUT:: + id : <id_given_in_input> result: { - "msg": "Deleted repository <reponame>", + "msg": "Deleted repository `<reponame>`", + "success": true } error: null @@ -675,15 +728,17 @@ api_key : "<api_key>" method : "grant_user_permission" args: { - "repo_name" : "<reponame>", - "username" : "<username>", + "repoid" : "<reponame or repo_id>" + "userid" : "<username or user_id>" "perm" : "(repository.(none|read|write|admin))", } OUTPUT:: + id : <id_given_in_input> result: { - "msg" : "Granted perm: <perm> for user: <username> in repo: <reponame>" + "msg" : "Granted perm: `<perm>` for user: `<username>` in repo: `<reponame>`", + "success": true } error: null @@ -701,14 +756,16 @@ api_key : "<api_key>" method : "revoke_user_permission" args: { - "repo_name" : "<reponame>", - "username" : "<username>", + "repoid" : "<reponame or repo_id>" + "userid" : "<username or user_id>" } OUTPUT:: + id : <id_given_in_input> result: { - "msg" : "Revoked perm for user: <suername> in repo: <reponame>" + "msg" : "Revoked perm for user: `<username>` in repo: `<reponame>`", + "success": true } error: null @@ -727,15 +784,17 @@ api_key : "<api_key>" method : "grant_users_group_permission" args: { - "repo_name" : "<reponame>", - "group_name" : "<usersgroupname>", + "repoid" : "<reponame or repo_id>" + "usersgroupid" : "<users group id or name>" "perm" : "(repository.(none|read|write|admin))", } OUTPUT:: + id : <id_given_in_input> result: { - "msg" : "Granted perm: <perm> for group: <usersgroupname> in repo: <reponame>" + "msg" : "Granted perm: `<perm>` for group: `<usersgroupname>` in repo: `<reponame>`", + "success": true } error: null @@ -752,13 +811,15 @@ api_key : "<api_key>" method : "revoke_users_group_permission" args: { - "repo_name" : "<reponame>", - "users_group" : "<usersgroupname>", + "repoid" : "<reponame or repo_id>" + "usersgroupid" : "<users group id or name>" } OUTPUT:: + id : <id_given_in_input> result: { - "msg" : "Revoked perm for group: <usersgroupname> in repo: <reponame>" + "msg" : "Revoked perm for group: `<usersgroupname>` in repo: `<reponame>`", + "success": true } error: null \ No newline at end of file