.. _api:

API

===

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

<your_server>/_admin/api

API ACCESS FOR WEB VIEWS

++++++++++++++++++++++++

API access can also be turned on for each view decorated with `@LoginRequired`

decorator. To enable API access simple change standard login decorator into

`@LoginRequired(api_access=True)`. After such a change view can be accessed

by adding a GET parameter to url `?api_key=<api_key>`. By default it's only

enabled on RSS/ATOM feed views.

API ACCESS

++++++++++

All clients are required to send JSON-RPC spec JSON data::

    {   

        "id:<id>,

        "api_key":"<api_key>",

        "method":"<method_name>",

        "args":{"<arg_key>":"<arg_val>"}

    }

Example call for autopulling remotes repos using curl::

    curl https://server.com/_admin/api -X POST -H 'content-type:text/plain' --data-binary '{"id":1,"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}'

Simply provide

 - *id* A value of any type, which is used to match the response with the request that it is replying to.

 - *api_key* for access and permission validation.

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

--------

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

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

rights.

INPUT::

    api_key : "<api_key>"

    method :  "get_user"

    args :    { 

                "username" : "<username>"

              }

OUTPUT::

    result: None if user does not exist or 

            {

                "id" :       "<id>",

                "username" : "<username>",

                "firstname": "<firstname>",

                "lastname" : "<lastname>",

                "email" :    "<email>",

                "active" :   "<bool>",

                "admin" :    "<bool>",

                "ldap" :     "<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" :     "<ldap_dn>"

              },

    	      …

            ]

    error:  null

create_user

-----------

INPUT::

    api_key : "<api_key>"

    method :  "create_user"

    args :    {

                "username" :  "<username>",

                "password" :  "<password>",

                "firstname" : "<firstname>",

                "lastname" :  "<lastname>",

                "email" :     "<useremail>"

                "active" :    "<bool> = True",

                "admin" :     "<bool> = False",

                "ldap_dn" :   "<ldap_dn> = None"

              }

OUTPUT::

    result: {

              "id" : "<new_user_id>",

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

            }

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

    api_key : "<api_key>"

    method :  "get_users_group"

    args :    {

                "group_name" : "<name>"

              }

OUTPUT::

    result : None if group not exist

             {

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

                              },

                              …

                            ]

             }

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

    api_key : "<api_key>"

    method :  "get_users_groups"

    args :    { }

OUTPUT::

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

	                            },

	    	                    …

	                          ]

	            }

              ]

    error : null

create_users_group

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

Creates new users group. This command can be executed only using api_key

belonging to user with admin rights

INPUT::

    api_key : "<api_key>"

    method :  "create_users_group"

    args:     {

                "group_name":  "<groupname>",

                "active":"<bool> = True"

              }

OUTPUT::

    result: {

              "id":  "<newusersgroupid>",

              "msg": "created new users group <groupname>"

            }

    error:  null

add_user_to_users_group

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

Adds a user to a users group. This command can be executed only using api_key

belonging to user with admin rights

INPUT::

    api_key : "<api_key>"

    method :  "add_user_users_group"

    args:     {

                "group_name" :  "<groupname>",

                "username" :   "<username>"

              }

OUTPUT::

    result: {

              "id":  "<newusersgroupmemberid>",

              "msg": "created new users group member"

            }

    error:  null

get_repo

--------

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

belonging to user with admin rights

INPUT::

    api_key : "<api_key>"

    method :  "get_repo"

    args:     {

                "repo_name" : "<reponame>"

              }

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

# -*- coding: utf-8 -*-

"""

    rhodecode.controllers.api

    ~~~~~~~~~~~~~~~~~~~~~~~~~

    API controller for RhodeCode

    :created_on: Aug 20, 2011

    :author: marcink

    :copyright: (C) 2011-2012 Marcin Kuzminski <marcin@python-works.com>

    :license: GPLv3, see COPYING for more details.

"""

# This program is free software; you can redistribute it and/or

# modify it under the terms of the GNU General Public License

# as published by the Free Software Foundation; version 2

# of the License or (at your opinion) any later version of the license.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program; if not, write to the Free Software

# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,

# MA  02110-1301, USA.

import traceback

import logging

from sqlalchemy.orm.exc import NoResultFound

from rhodecode.controllers.api import JSONRPCController, JSONRPCError

from rhodecode.lib.auth import HasPermissionAllDecorator, \

    HasPermissionAnyDecorator

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.repo_permission import RepositoryPermissionModel

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')

    def get_user(self, apiuser, username):

        """"

        Get a user by username

        :param apiuser:

        :param username:

        """

        user = User.get_by_username(username)

        if not user:

            return None

        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=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=user.ldap_dn

                )

            )

        return result

    @HasPermissionAllDecorator('hg.admin')

    def create_user(self, apiuser, username, password, firstname,

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

        """

        :param apiuser:

        :param username:

        :param password:

        :param name:

        :param lastname:

        :param email:

        :param active:

        :param admin:

        :param ldap_dn:

        """

        if User.get_by_username(username):

            raise JSONRPCError("user %s already exist" % username)

        try:

            usr = UserModel().create_or_update(

                username, password, email, firstname,

                lastname, active, admin, ldap_dn

            )

            Session.commit()

            return dict(

                id=usr.user_id,

                msg='created new user %s' % username

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to create user %s' % username)

    @HasPermissionAllDecorator('hg.admin')

    def get_users_group(self, apiuser, group_name):

        """"

        Get users group by name

        :param apiuser:

        :param group_name:

        """

        users_group = UsersGroup.get_by_group_name(group_name)

        if not users_group:

            return None

        members = []

        for user in users_group.members:

            user = user.user

            members.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=user.ldap_dn))

        return dict(id=users_group.users_group_id,

                    group_name=users_group.users_group_name,

                    active=users_group.users_group_active,

                    members=members)

    @HasPermissionAllDecorator('hg.admin')

    def get_users_groups(self, apiuser):

        """"

        Get all users groups

        :param apiuser:

        """

        result = []

        for users_group in UsersGroup.getAll():

            members = []

            for user in users_group.members:

                user = user.user

                members.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=user.ldap_dn))

            result.append(dict(id=users_group.users_group_id,

                                group_name=users_group.users_group_name,

                                active=users_group.users_group_active,

                                members=members))

        return result

    @HasPermissionAllDecorator('hg.admin')

    def create_users_group(self, apiuser, group_name, active=True):

        """

        Creates an new usergroup

        :param group_name:

        :param active:

        """

        if self.get_users_group(apiuser, group_name):

            raise JSONRPCError("users group %s already exist" % group_name)

        try:

            ug = UsersGroupModel().create(name=group_name, active=active)

            Session.commit()

            return dict(id=ug.users_group_id,

                        msg='created new users group %s' % group_name)

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to create group %s' % group_name)

    @HasPermissionAllDecorator('hg.admin')

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

        """"

        Add a user to 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)

            try:

                user = User.get_by_username(username)

            except NoResultFound:

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

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

            Session.commit()

            return dict(id=ugm.users_group_member_id,

                        msg='created new users group member')

        except Exception:

            log.error(traceback.format_exc())

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

    @HasPermissionAnyDecorator('hg.admin')

    def get_repo(self, apiuser, repo_name):

        """"

        Get repository by name

        :param apiuser:

        :param repo_name:

        """

        repo = Repository.get_by_repo_name(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