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

    {   

        "id":<id>, # matching id sent by request

        "result": "<result>"|null, # JSON formatted result, null if any errors

        "error": "null"|<error_message> # JSON formatted error (if any)

    }

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 CLIENT

++++++++++

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.

To get started quickly simply run::

  rhodecode-api _create_config --apikey=<youapikey> --apihost=<rhodecode host>

This will create a file named .config in the directory you executed it storing

json config file with credentials. You can skip this step and always provide

both of the arguments to be able to communicate with server

after that simply run any api command for example get_repo::

 rhodecode-api get_repo

 calling {"api_key": "<apikey>", "id": 75, "args": {}, "method": "get_repo"} to http://127.0.0.1:5000

 rhodecode said:

 {'error': 'Missing non optional `repoid` arg in JSON DATA',

  'id': 75,

  'result': None}

Ups looks like we forgot to add an argument

Let's try again now giving the repoid as parameters::

    rhodecode-api get_repo repoid:rhodecode   

    calling {"api_key": "<apikey>", "id": 39, "args": {"repoid": "rhodecode"}, "method": "get_repo"} to http://127.0.0.1:5000

    rhodecode said:

    {'error': None,

     'id': 39,

     'result': <json data...>}

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::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "pull"

    args :    {

                "repoid" : "<reponame or repo_id>"

              }

OUTPUT::

    id : <id_given_in_input>

    result : "Pulled from `<reponame>`"

    error :  null

rescan_repos

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

Dispatch rescan repositories action. If remove_obsolete is set

RhodeCode will delete repos that are in database but not in the filesystem.

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

rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "rescan_repos"

    args :    {

                "remove_obsolete" : "<boolean = Optional(False)>"

              }

OUTPUT::

    id : <id_given_in_input>

    result : "{'added': [<list of names of added repos>], 

               'removed': [<list of names of removed repos>]}"

    error :  null

lock

----

Set locking state on given repository by given user.

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

rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "lock"

    args :    {

                "repoid" : "<reponame or repo_id>"

                "userid" : "<user_id or username>",

                "locked" : "<bool true|false>"

              }

OUTPUT::

    id : <id_given_in_input>

    result : "User `<username>` set lock state for repo `<reponame>` to `true|false`"

    error :  null

show_ip

-------

Shows IP address as seen from RhodeCode server, together with all

defined IP addresses for given user.

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

rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "show_ip"

    args :    {

                "userid" : "<user_id or username>",

              }

OUTPUT::

    id : <id_given_in_input>

    result : {

                 "ip_addr_server": <ip_from_clien>",

                 "user_ips": [

                                {

                                   "ip_addr": "<ip_with_mask>",

                                   "ip_range": ["<start_ip>", "<end_ip>"],

                                },

                                ...

                             ]

             }

    error :  null

get_user

--------

Get's an user by username or user_id, Returns empty result if user is not found.

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

rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_user"

    args :    { 

                "userid" : "<username or user_id>"

              }

OUTPUT::

    id : <id_given_in_input>

    result: None if user does not exist or 

            {

                "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>",

                "permissions": {

                    "global": ["hg.create.repository",

                               "repository.read",

                               "hg.register.manual_activate"],

                    "repositories": {"repo1": "repository.none"},

                    "repositories_groups": {"Group1": "group.read"}

                 },

            }

    error:  null

get_users

---------

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

belonging to user with admin rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_users"

    args :    { }

OUTPUT::

    id : <id_given_in_input>

    result: [

              {

                "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

create_user

-----------

Creates new user. This command can 

be executed only using api_key belonging to user with admin rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "create_user"

    args :    {

                "username" :  "<username>",

                "email" :     "<useremail>",

                "password" :  "<password>",

                "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: {

              "msg" : "created new user `<username>`",

              "user": {

                "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

update_user

-----------

updates given user if such user exists. This command can 

be executed only using api_key belonging to user with admin rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "update_user"

    args :    {

                "userid" : "<user_id or username>",

                "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: {

              "msg" : "updated user ID:<userid> <username>",

              "user": {

                "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

delete_user

-----------

deletes givenuser if such user exists. This command can 

be executed only using api_key belonging to user with admin rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "delete_user"

    args :    {

                "userid" : "<user_id or username>",

              }

OUTPUT::

    id : <id_given_in_input>

    result: {

              "msg" : "deleted user ID:<userid> <username>",

              "user": null

            }

    error:  null

get_users_group

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

Gets an existing users group. This command can be executed only using api_key

belonging to user with admin rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_users_group"

    args :    {

                "usersgroupid" : "<users group id or name>"

              }

OUTPUT::

    id : <id_given_in_input>

    result : None if group not exist

             {

               "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

get_users_groups

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

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

api_key belonging to user with admin rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_users_groups"

    args :    { }

OUTPUT::

    id : <id_given_in_input>

    result : [

               {

               "users_group_id" : "<id>",

               "group_name" :     "<groupname>",

               "active":          "<bool>",

               },

        Setter that will always make sure we use unicode in app_settings_value

        :param val:

        """

        self._app_settings_value = safe_unicode(val)

    def __unicode__(self):

        return u"<%s('%s:%s')>" % (

            self.__class__.__name__,

            self.app_settings_name, self.app_settings_value

        )

    @classmethod

    def get_by_name(cls, key):

        return cls.query()\

            .filter(cls.app_settings_name == key).scalar()

    @classmethod

    def get_by_name_or_create(cls, key):

        res = cls.get_by_name(key)

        if not res:

            res = cls(key)

        return res

    @classmethod

    def get_app_settings(cls, cache=False):

        ret = cls.query()

        if cache:

            ret = ret.options(FromCache("sql_cache_short", "get_hg_settings"))

        if not ret:

            raise Exception('Could not get application settings !')

        settings = {}

        for each in ret:

            settings['rhodecode_' + each.app_settings_name] = \

                each.app_settings_value

        return settings

    @classmethod

    def get_ldap_settings(cls, cache=False):

        ret = cls.query()\

                .filter(cls.app_settings_name.startswith('ldap_')).all()

        fd = {}

        for row in ret:

            fd.update({row.app_settings_name: row.app_settings_value})

        return fd

    @classmethod

    def get_default_repo_settings(cls, cache=False, strip_prefix=False):

        ret = cls.query()\

                .filter(cls.app_settings_name.startswith('default_')).all()

        fd = {}

        for row in ret:

            key = row.app_settings_name

            if strip_prefix:

                key = remove_prefix(key, prefix='default_')

            fd.update({key: row.app_settings_value})

        return fd

class RhodeCodeUi(Base, BaseModel):

    __tablename__ = 'rhodecode_ui'

    __table_args__ = (

        UniqueConstraint('ui_key'),

        {'extend_existing': True, 'mysql_engine': 'InnoDB',

         'mysql_charset': 'utf8'}

    )

    HOOK_UPDATE = 'changegroup.update'

    HOOK_REPO_SIZE = 'changegroup.repo_size'

    HOOK_PUSH = 'changegroup.push_logger'

    HOOK_PRE_PUSH = 'prechangegroup.pre_push'

    HOOK_PULL = 'outgoing.pull_logger'

    HOOK_PRE_PULL = 'preoutgoing.pre_pull'

    ui_id = Column("ui_id", Integer(), nullable=False, unique=True, default=None, primary_key=True)

    ui_section = Column("ui_section", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)

    ui_key = Column("ui_key", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)

    ui_value = Column("ui_value", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)

    ui_active = Column("ui_active", Boolean(), nullable=True, unique=None, default=True)

    @classmethod

    def get_by_key(cls, key):

        return cls.query().filter(cls.ui_key == key).scalar()

    @classmethod

    def get_builtin_hooks(cls):

        q = cls.query()

        q = q.filter(cls.ui_key.in_([cls.HOOK_UPDATE, cls.HOOK_REPO_SIZE,

                                     cls.HOOK_PUSH, cls.HOOK_PRE_PUSH,

                                     cls.HOOK_PULL, cls.HOOK_PRE_PULL]))

        return q.all()

    @classmethod

    def get_custom_hooks(cls):

        q = cls.query()

        q = q.filter(~cls.ui_key.in_([cls.HOOK_UPDATE, cls.HOOK_REPO_SIZE,

                                      cls.HOOK_PUSH, cls.HOOK_PRE_PUSH,

                                      cls.HOOK_PULL, cls.HOOK_PRE_PULL]))

        q = q.filter(cls.ui_section == 'hooks')

        return q.all()

    @classmethod

    def get_repos_location(cls):

        return cls.get_by_key('/').ui_value

    @classmethod

    def create_or_update_hook(cls, key, val):

        new_ui = cls.get_by_key(key) or cls()

        new_ui.ui_section = 'hooks'

        new_ui.ui_active = True

        new_ui.ui_key = key

        new_ui.ui_value = val

        Session().add(new_ui)

    def __repr__(self):

        return '<DB:%s[%s:%s]>' % (self.__class__.__name__, self.ui_key,

                                   self.ui_value)

class User(Base, BaseModel):

    __tablename__ = 'users'

    __table_args__ = (

        UniqueConstraint('username'), UniqueConstraint('email'),

        Index('u_username_idx', 'username'),

        Index('u_email_idx', 'email'),

        {'extend_existing': True, 'mysql_engine': 'InnoDB',

         'mysql_charset': 'utf8'}

    )

    DEFAULT_USER = 'default'

    DEFAULT_PERMISSIONS = [

        'hg.register.manual_activate', 'hg.create.repository',

        'hg.fork.repository', 'repository.read', 'group.read'

    ]

    user_id = Column("user_id", Integer(), nullable=False, unique=True, default=None, primary_key=True)

    username = Column("username", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)

    password = Column("password", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)

    active = Column("active", Boolean(), nullable=True, unique=None, default=True)

    admin = Column("admin", Boolean(), nullable=True, unique=None, default=False)

    name = Column("firstname", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)

    lastname = Column("lastname", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)

    _email = Column("email", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)

    last_login = Column("last_login", DateTime(timezone=False), nullable=True, unique=None, default=None)

    ldap_dn = Column("ldap_dn", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)

    api_key = Column("api_key", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)

    inherit_default_permissions = Column("inherit_default_permissions", Boolean(), nullable=False, unique=None, default=True)

    user_log = relationship('UserLog')

    user_perms = relationship('UserToPerm', primaryjoin="User.user_id==UserToPerm.user_id", cascade='all')

    repositories = relationship('Repository')

    user_followers = relationship('UserFollowing', primaryjoin='UserFollowing.follows_user_id==User.user_id', cascade='all')

    followings = relationship('UserFollowing', primaryjoin='UserFollowing.user_id==User.user_id', cascade='all')

    repo_to_perm = relationship('UserRepoToPerm', primaryjoin='UserRepoToPerm.user_id==User.user_id', cascade='all')

    repo_group_to_perm = relationship('UserRepoGroupToPerm', primaryjoin='UserRepoGroupToPerm.user_id==User.user_id', cascade='all')

    group_member = relationship('UsersGroupMember', cascade='all')

    notifications = relationship('UserNotification', cascade='all')

    # notifications assigned to this user

    user_created_notifications = relationship('Notification', cascade='all')

    # comments created by this user

    user_comments = relationship('ChangesetComment', cascade='all')

    #extra emails for this user

    user_emails = relationship('UserEmailMap', cascade='all')

    @hybrid_property

    def email(self):

        return self._email

    @email.setter

    def email(self, val):

        self._email = val.lower() if val else None

    @property

    def firstname(self):

        # alias for future

        return self.name

    @property

    def emails(self):

        other = UserEmailMap.query().filter(UserEmailMap.user==self).all()

        return [self.email] + [x.email for x in other]

    @property

    def username_and_name(self):

        return '%s (%s %s)' % (self.username, self.firstname, self.lastname)

    @property

    def full_name(self):

        return '%s %s' % (self.firstname, self.lastname)

    @property

    def full_name_or_username(self):

        return ('%s %s' % (self.firstname, self.lastname)

                if (self.firstname and self.lastname) else self.username)

    @property

    def full_contact(self):

        return '%s %s <%s>' % (self.firstname, self.lastname, self.email)

    @property

    def short_contact(self):

        return '%s %s' % (self.firstname, self.lastname)

    @property

    def is_admin(self):

        return self.admin

    def __unicode__(self):

        return u"<%s('id:%s:%s')>" % (self.__class__.__name__,

                                     self.user_id, self.username)

    @classmethod

    def get_by_username(cls, username, case_insensitive=False, cache=False):

        if case_insensitive:

            q = cls.query().filter(cls.username.ilike(username))

        else:

            q = cls.query().filter(cls.username == username)

        if cache:

            q = q.options(FromCache(

                            "sql_cache_short",

                            "get_user_%s" % _hash_key(username)

                          )

            )

        return q.scalar()

    @classmethod

    def get_by_api_key(cls, api_key, cache=False):

        q = cls.query().filter(cls.api_key == api_key)

        if cache:

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

                                    "get_api_key_%s" % api_key))

        return q.scalar()

    @classmethod

    def get_by_email(cls, email, case_insensitive=False, cache=False):

        if case_insensitive:

            q = cls.query().filter(cls.email.ilike(email))

        else:

            q = cls.query().filter(cls.email == email)

        if cache:

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

                                    "get_email_key_%s" % email))

        ret = q.scalar()

        if ret is None:

            q = UserEmailMap.query()

            # try fetching in alternate email map

            if case_insensitive:

                q = q.filter(UserEmailMap.email.ilike(email))

            else:

                q = q.filter(UserEmailMap.email == email)

            q = q.options(joinedload(UserEmailMap.user))

            if cache:

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

                                        "get_email_map_key_%s" % email))

            ret = getattr(q.scalar(), 'user', None)

        return ret

    def update_lastlogin(self):

        """Update user lastlogin"""

        self.last_login = datetime.datetime.now()

        Session().add(self)

        log.debug('updated user %s lastlogin' % self.username)

    def get_api_data(self):

        """

        Common function for generating user related data for API

        """

        user = self

        data = dict(

            user_id=user.user_id,

            username=user.username,

            firstname=user.name,

            lastname=user.lastname,

            email=user.email,

            emails=user.emails,

            api_key=user.api_key,

            active=user.active,

            admin=user.admin,

            ldap_dn=user.ldap_dn,

            last_login=user.last_login,

        )

        return data

    def __json__(self):

        data = dict(

            full_name=self.full_name,

            full_name_or_username=self.full_name_or_username,

            short_contact=self.short_contact,

            full_contact=self.full_contact

        )

        data.update(self.get_api_data())

        return data

class UserEmailMap(Base, BaseModel):

    __tablename__ = 'user_email_map'

    __table_args__ = (

        Index('uem_email_idx', 'email'),

        UniqueConstraint('email'),

        {'extend_existing': True, 'mysql_engine': 'InnoDB',

         'mysql_charset': 'utf8'}

    )

    __mapper_args__ = {}

    email_id = Column("email_id", Integer(), nullable=False, unique=True, default=None, primary_key=True)

    user_id = Column("user_id", Integer(), ForeignKey('users.user_id'), nullable=True, unique=None, default=None)

    _email = Column("email", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=False, default=None)

    user = relationship('User', lazy='joined')

    @validates('_email')

    def validate_email(self, key, email):

        # check if this email is not main one

        main_email = Session().query(User).filter(User.email == email).scalar()

        if main_email is not None:

            raise AttributeError('email %s is present is user table' % email)

        return email

    @hybrid_property

    def email(self):

        return self._email

    @email.setter

    def email(self, val):

        self._email = val.lower() if val else None

class UserIpMap(Base, BaseModel):

    __tablename__ = 'user_ip_map'

    __table_args__ = (

        UniqueConstraint('user_id', 'ip_addr'),

        {'extend_existing': True, 'mysql_engine': 'InnoDB',

         'mysql_charset': 'utf8'}

    )

    __mapper_args__ = {}

    ip_id = Column("ip_id", Integer(), nullable=False, unique=True, default=None, primary_key=True)

    user_id = Column("user_id", Integer(), ForeignKey('users.user_id'), nullable=True, unique=None, default=None)

    ip_addr = Column("ip_addr", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=False, default=None)

    user = relationship('User', lazy='joined')

    @classmethod

    def _get_ip_range(cls, ip_addr):

        from rhodecode.lib import ipaddr

        net = ipaddr.IPv4Network(ip_addr)

        return [str(net.network), str(net.broadcast)]

    def __json__(self):

        return dict(

          ip_addr=self.ip_addr,

          ip_range=self._get_ip_range(self.ip_addr)

        )

class UserLog(Base, BaseModel):

    __tablename__ = 'user_logs'

    __table_args__ = (

        {'extend_existing': True, 'mysql_engine': 'InnoDB',

         'mysql_charset': 'utf8'},

    )

    user_log_id = Column("user_log_id", Integer(), nullable=False, unique=True, default=None, primary_key=True)

    user_id = Column("user_id", Integer(), ForeignKey('users.user_id'), nullable=True, unique=None, default=None)

    username = Column("username", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)

    repository_id = Column("repository_id", Integer(), ForeignKey('repositories.repo_id'), nullable=True)

    repository_name = Column("repository_name", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)

    user_ip = Column("user_ip", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)

    action = Column("action", UnicodeText(1200000, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)

    action_date = Column("action_date", DateTime(timezone=False), nullable=True, unique=None, default=None)

    @property

    def action_as_day(self):

        return datetime.date(*self.action_date.timetuple()[:3])

    user = relationship('User')

    repository = relationship('Repository', cascade='')

class UsersGroup(Base, BaseModel):

    __tablename__ = 'users_groups'

    __table_args__ = (

        {'extend_existing': True, 'mysql_engine': 'InnoDB',

         'mysql_charset': 'utf8'},

    )

    users_group_id = Column("users_group_id", Integer(), nullable=False, unique=True, default=None, primary_key=True)

    users_group_name = Column("users_group_name", String(255, convert_unicode=False, assert_unicode=None), nullable=False, unique=True, default=None)

    users_group_active = Column("users_group_active", Boolean(), nullable=True, unique=None, default=None)

    inherit_default_permissions = Column("users_group_inherit_default_permissions", Boolean(), nullable=False, unique=None, default=True)

    members = relationship('UsersGroupMember', cascade="all, delete, delete-orphan", lazy="joined")

    users_group_to_perm = relationship('UsersGroupToPerm', cascade='all')

    users_group_repo_to_perm = relationship('UsersGroupRepoToPerm', cascade='all')

    def __unicode__(self):

        return u'<userGroup(%s)>' % (self.users_group_name)

    @classmethod

    def get_by_group_name(cls, group_name, cache=False,

                          case_insensitive=False):

        if case_insensitive:

            q = cls.query().filter(cls.users_group_name.ilike(group_name))

        else:

            q = cls.query().filter(cls.users_group_name == group_name)

        if cache:

            q = q.options(FromCache(

                            "sql_cache_short",

                            "get_user_%s" % _hash_key(group_name)

                          )

            )

        return q.scalar()

    @classmethod

    def get(cls, users_group_id, cache=False):

        users_group = cls.query()

        if cache:

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

                                    "get_users_group_%s" % users_group_id))

        return users_group.get(users_group_id)

    def get_api_data(self):

        users_group = self

        data = dict(

            users_group_id=users_group.users_group_id,

            group_name=users_group.users_group_name,