- *method* is name of method to call

 - *args* is an key:value list of arguments to pass to method

.. note::

    api_key can be found in your user account page

RhodeCode API will return always a JSON-RPC response::

    {   

        "id":<id>,

        "result": "<result>",

        "error": null

    }

All responses from API will be `HTTP/1.0 200 OK`, if there's an error while

calling api *error* key from response will contain failure description

and result will be null.

API METHODS

+++++++++++

pull

----

Pulls given repo from remote location. Can be used to automatically keep

remote repos up to date. This command can be executed only using api_key

belonging to user with admin rights

INPUT::

    api_key : "<api_key>"

    method :  "pull"

    args :    {

                "repo_name" : "<reponame>"

              }

OUTPUT::

    result : "Pulled from <reponame>"

    error :  null

get_user

--------

This command can be executed only using api_key belonging to user with admin 

rights.

INPUT::

    api_key : "<api_key>"

    method :  "get_user"

    args :    { 

              }

OUTPUT::

    result: None if user does not exist or 

            {

                "id" :       "<id>",

                "username" : "<username>",

                "firstname": "<firstname>",

                "lastname" : "<lastname>",

                "email" :    "<email>",

                "active" :   "<bool>",

                "admin" :    "<bool>",

                "ldap_dn" :  "<ldap_dn>"

            }

    error:  null

get_users

---------

Lists all existing users. This command can be executed only using api_key

belonging to user with admin rights.

INPUT::

    api_key : "<api_key>"

    method :  "get_users"

    args :    { }

OUTPUT::

    result: [

              {

                "id" :       "<id>",

                "username" : "<username>",

                "firstname": "<firstname>",

                "lastname" : "<lastname>",

                "email" :    "<email>",

                "active" :   "<bool>",

                "admin" :    "<bool>",

                "ldap_dn" :  "<ldap_dn>"

              },

    	      …

            ]

    error:  null

    api_key : "<api_key>"

    method :  "add_user_users_group"

    args:     {

                "group_name" :  "<groupname>",

                "username" :   "<username>"

              }

OUTPUT::

    result: {

              "id":  "<newusersgroupmemberid>",

              "success": True|False # depends on if member is in group

              "msg": "added member <username> to users group <groupname> | 

                      User is already in that group"

            }

    error:  null

remove_user_from_users_group

----------------------------

Removes a user from a users group. If user is not in given group success will

be `false`. This command can be executed only 

using api_key belonging to user with admin rights

INPUT::

    api_key : "<api_key>"

    method :  "remove_user_from_users_group"

    args:     {

                "group_name" :  "<groupname>",

                "username" :   "<username>"

              }

OUTPUT::

    result: {

              "success":  True|False,  # depends on if member is in group

              "msg": "removed member <username> from users group <groupname> | 

                      User wasn't in group"

            }

    error:  null

get_repo

--------

INPUT::

    api_key : "<api_key>"

    method :  "get_repo"

    args:     {

              }

OUTPUT::

    result: None if repository does not exist or

            {

                "id" :          "<id>",

                "repo_name" :   "<reponame>"

                "type" :        "<type>",

                "description" : "<description>",

                "members" :     [

                                  { "id" :         "<userid>",

                                    "username" :   "<username>",

                                    "firstname":   "<firstname>",

                                    "lastname" :   "<lastname>",

                                    "email" :      "<email>",

                                    "active" :     "<bool>",

                                    "admin" :      "<bool>",

                                    "ldap" :       "<ldap_dn>",

                                    "permission" : "repository.(read|write|admin)"

                                  },

                                  …

                                  {

                                    "id" :       "<usersgroupid>",

                                    "name" :     "<usersgroupname>",

                                    "active":    "<bool>",

                                    "permission" : "repository.(read|write|admin)"

                                  },

                                  …

                                ]

            }

    error:  null

get_repos

---------

Lists all existing repositories. This command can be executed only using api_key

belonging to user with admin rights

INPUT::

    api_key : "<api_key>"

    method :  "get_repos"

    args:     { }

OUTPUT::

from rhodecode.model.meta import Session

from rhodecode.model.scm import ScmModel

from rhodecode.model.db import User, UsersGroup, RepoGroup, Repository

from rhodecode.model.repo import RepoModel

from rhodecode.model.user import UserModel

from rhodecode.model.users_group import UsersGroupModel

from rhodecode.model.repos_group import ReposGroupModel

log = logging.getLogger(__name__)

class ApiController(JSONRPCController):

    """

    API Controller

    Each method needs to have USER as argument this is then based on given

    API_KEY propagated as instance of user object

    Preferably this should be first argument also

    Each function should also **raise** JSONRPCError for any

    errors that happens

    """

    @HasPermissionAllDecorator('hg.admin')

    def pull(self, apiuser, repo_name):

        """

        Dispatch pull action on given repo

        :param user:

        :param repo_name:

        """

        if Repository.is_valid(repo_name) is False:

            raise JSONRPCError('Unknown repo "%s"' % repo_name)

        try:

            ScmModel().pull_changes(repo_name, self.rhodecode_user.username)

            return 'Pulled from %s' % repo_name

        except Exception:

            raise JSONRPCError('Unable to pull changes from "%s"' % repo_name)

    @HasPermissionAllDecorator('hg.admin')

        """"

        Get a user by username

        :param apiuser:

        :param username:

        """

        if user is None:

            return user

        return dict(

            id=user.user_id,

            username=user.username,

            firstname=user.name,

            lastname=user.lastname,

            email=user.email,

            active=user.active,

            admin=user.admin,

            ldap_dn=user.ldap_dn

        )

    @HasPermissionAllDecorator('hg.admin')

    def get_users(self, apiuser):

        """"

        Get all users

        :param apiuser:

        """

        result = []

        for user in User.getAll():

            result.append(

                dict(

                    id=user.user_id,

                    username=user.username,

                    firstname=user.name,

                    lastname=user.lastname,

                    email=user.email,

                    active=user.active,

                    admin=user.admin,

                    ldap_dn=user.ldap_dn

                )

            )

        return result

    @HasPermissionAllDecorator('hg.admin')

    def create_user(self, apiuser, username, email, password, firstname=None,

                    lastname=None, active=True, admin=False, ldap_dn=None):

        """

        Create new user

        :param apiuser:

        :param username:

        :param password:

        :param email:

            user = User.get_by_username(username)

            if user is None:

                raise JSONRPCError('unknown user %s' % username)

            ugm = UsersGroupModel().add_user_to_group(users_group, user)

            success = True if ugm != True else False

            msg = 'added member %s to users group %s' % (username, group_name)

            msg = msg if success else 'User is already in that group'

            Session.commit()

            return dict(

                id=ugm.users_group_member_id if ugm != True else None,

                success=success,

                msg=msg

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to add users group member')

    @HasPermissionAllDecorator('hg.admin')

    def remove_user_from_users_group(self, apiuser, group_name, username):

        """

        Remove user from a group

        :param apiuser

        :param group_name

        :param username

        """

        try:

            users_group = UsersGroup.get_by_group_name(group_name)

            if not users_group:

                raise JSONRPCError('unknown users group %s' % group_name)

            user = User.get_by_username(username)

            if user is None:

                raise JSONRPCError('unknown user %s' % username)

            success = UsersGroupModel().remove_user_from_group(users_group, user)

            msg = 'removed member %s from users group %s' % (username, group_name)

            msg = msg if success else "User wasn't in group"

            Session.commit()

            return dict(success=success, msg=msg)

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to remove user from group')

    @HasPermissionAnyDecorator('hg.admin')

        """"

        Get repository by name

        :param apiuser:

        :param repo_name:

        """

        if repo is None:

            raise JSONRPCError('unknown repository %s' % repo)

        members = []

        for user in repo.repo_to_perm:

            perm = user.permission.permission_name

            user = user.user

            members.append(

                dict(

                    type_="user",

                    id=user.user_id,

                    username=user.username,

                    firstname=user.name,

                    lastname=user.lastname,

                    email=user.email,

                    active=user.active,

                    admin=user.admin,

                    ldap=user.ldap_dn,

                    permission=perm

                )

            )

        for users_group in repo.users_group_to_perm:

            perm = users_group.permission.permission_name

            users_group = users_group.users_group

            members.append(

                dict(

                    type_="users_group",

                    id=users_group.users_group_id,

                    name=users_group.users_group_name,

                    active=users_group.users_group_active,

                    permission=perm

                )

            )

        return dict(

            id=repo.repo_id,

            repo_name=repo.repo_name,

            type=repo.repo_type,

            description=repo.description,

            members=members

        )

    @HasPermissionAnyDecorator('hg.admin')

    def get_repos(self, apiuser):

        """"

        Get all repositories

        :param apiuser:

from rhodecode.model import BaseModel

from rhodecode.model.db import Repository, UserRepoToPerm, User, Permission, \

    Statistics, UsersGroup, UsersGroupRepoToPerm, RhodeCodeUi, RepoGroup

log = logging.getLogger(__name__)

class RepoModel(BaseModel):

    def __get_user(self, user):

        return self._get_instance(User, user, callback=User.get_by_username)

    def __get_users_group(self, users_group):

        return self._get_instance(UsersGroup, users_group,

                                  callback=UsersGroup.get_by_group_name)

    def __get_repos_group(self, repos_group):

        return self._get_instance(RepoGroup, repos_group,

                                  callback=RepoGroup.get_by_group_name)

    def __get_repo(self, repository):

        return self._get_instance(Repository, repository,

                                  callback=Repository.get_by_repo_name)

    def __get_perm(self, permission):

        return self._get_instance(Permission, permission,

                                  callback=Permission.get_by_key)

    @LazyProperty

    def repos_path(self):

        """

        Get's the repositories root path from database

        """

        q = self.sa.query(RhodeCodeUi).filter(RhodeCodeUi.ui_key == '/').one()

        return q.ui_value

    def get(self, repo_id, cache=False):

        repo = self.sa.query(Repository)\

            .filter(Repository.repo_id == repo_id)

        if cache:

            repo = repo.options(FromCache("sql_cache_short",

                                          "get_repo_%s" % repo_id))

        return repo.scalar()

    def get_by_repo_name(self, repo_name, cache=False):

        repo = self.sa.query(Repository)\

            .filter(Repository.repo_name == repo_name)

        if cache:

            repo = repo.options(FromCache("sql_cache_short",

                                          "get_repo_%s" % repo_name))

        return repo.scalar()

    def get_users_js(self):

        users = self.sa.query(User).filter(User.active == True).all()

        u_tmpl = '''{id:%s, fname:"%s", lname:"%s", nname:"%s"},'''

        users_array = '[%s]' % '\n'.join([u_tmpl % (u.user_id, u.name,

                                                    u.lastname, u.username)

                                        for u in users])

        return users_array

    def get_users_groups_js(self):

        users_groups = self.sa.query(UsersGroup)\

            .filter(UsersGroup.users_group_active == True).all()

        g_tmpl = '''{id:%s, grname:"%s",grmembers:"%s"},'''

        users_groups_array = '[%s]' % '\n'.join([g_tmpl % \

                                    (gr.users_group_id, gr.users_group_name,

                                     len(gr.members))

                                        for gr in users_groups])

        return users_groups_array

    def _get_defaults(self, repo_name):

        """

        Get's information about repository, and returns a dict for

        usage in forms

        :param repo_name:

        """

        repo_info = Repository.get_by_repo_name(repo_name)

        if repo_info is None:

            return None

        defaults = repo_info.get_dict()

        group, repo_name = repo_info.groups_and_repo

        defaults['repo_name'] = repo_name

        defaults['repo_group'] = getattr(group[-1] if group else None,

                                         'group_id', None)