.. _api:

API

===

Starting from RhodeCode version 1.2 a simple API was implemented.

There's one schema for calling all api methods. API is implemented

Clients need to send JSON data in such format::

    {

        "api_key":"<api_key>",

        "method":"<method_name>",

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

    }

Simply provide api_key for access and permission validation

method is name of method to call

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

.. note::

    api_key can be found in your user account page    

And will receive JSON formatted answer::

    {

        "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 upto date. This command can be executed only using admin users

api_key

::

    method: "pull"

    args: {"repo":<repo_name>}

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

"""

    rhodecode.controllers.api

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

    JSON RPC controller

    :created_on: Aug 20, 2011

    :author: marcink

    :copyright: (C) 2009-2010 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 inspect

import json

import logging

import types

import urllib

from paste.response import replace_header

from pylons.controllers import WSGIController

from pylons.controllers.util import Response

from webob.exc import HTTPNotFound, HTTPForbidden, HTTPInternalServerError, \

HTTPBadRequest, HTTPError

from rhodecode.lib.auth import AuthUser

log = logging.getLogger('JSONRPC')

class JSONRPCError(BaseException):

    def __init__(self, message):

        self.message = message

    def __str__(self):

        return str(self.message)

def jsonrpc_error(message, code=None):

    """Generate a Response object with a JSON-RPC error body"""

    return Response(body=json.dumps(dict(result=None,

                                         error=message)))

class JSONRPCController(WSGIController):

    """

     A WSGI-speaking JSON-RPC controller class

     See the specification:

     <http://json-rpc.org/wiki/specification>`.

     Valid controller return values should be json-serializable objects.

     Sub-classes should catch their exceptions and raise JSONRPCError

     if they want to pass meaningful errors to the client.

     """

    def _get_method_args(self):

        """

        Return `self._rpc_args` to dispatched controller method

        chosen by __call__

        """

        return self._rpc_args

    def __call__(self, environ, start_response):

        """

        Parse the request body as JSON, look up the method on the

        controller and if it exists, dispatch to it.

        """

        if 'CONTENT_LENGTH' not in environ:

            log.debug("No Content-Length")

        else:

            length = environ['CONTENT_LENGTH'] or 0

            length = int(environ['CONTENT_LENGTH'])

            log.debug('Content-Length: %s', length)

        if length == 0:

            log.debug("Content-Length is 0")

        raw_body = environ['wsgi.input'].read(length)

        try:

            json_body = json.loads(urllib.unquote_plus(raw_body))

        except ValueError as e:

            #catch JSON errors Here

                                 % (e, urllib.unquote_plus(raw_body)))

        #check AUTH based on API KEY

        try:

            self._req_api_key = json_body['api_key']

            self._req_method = json_body['method']

            self._req_params = json_body['args']

            log.debug('method: %s, params: %s',

                      self._req_method,

                      self._req_params)

        except KeyError as e:

            return jsonrpc_error(message='Incorrect JSON query missing %s' % e)

        #check if we can find this session using api_key

        try:

            u = User.get_by_api_key(self._req_api_key)

            auth_u = AuthUser(u.user_id, self._req_api_key)

        except Exception as e:

            return jsonrpc_error(message='Invalid API KEY')

        self._error = None

        try:

            self._func = self._find_method()

        except AttributeError, e:

        # now that we have a method, add self._req_params to

        # self.kargs and dispatch control to WGIController

        arglist = inspect.getargspec(self._func)[0][1:]

        # this is little trick to inject logged in user for 

        # perms decorators to work they expect the controller class to have

        # rhodecode_user set

        self.rhodecode_user = auth_u

        if 'user' not in arglist:

                                 'authentication (missing user param)' %

                                 self._func.__name__)

        # get our arglist and check if we provided them as args

        for arg in arglist:

            if arg == 'user':

                # user is something translated from api key and this is

                # checked before

                continue

            if not self._req_params or arg not in self._req_params:

        self._rpc_args = dict(user=u)

        self._rpc_args.update(self._req_params)

        self._rpc_args['action'] = self._req_method

        self._rpc_args['environ'] = environ

        self._rpc_args['start_response'] = start_response

        status = []

        headers = []

        exc_info = []

        def change_content(new_status, new_headers, new_exc_info=None):

            status.append(new_status)

            headers.extend(new_headers)

            exc_info.append(new_exc_info)

        output = WSGIController.__call__(self, environ, change_content)

        output = list(output)

        headers.append(('Content-Length', str(len(output[0]))))

        replace_header(headers, 'Content-Type', 'application/json')

        start_response(status[0], headers, exc_info[0])

        return output

    def _dispatch_call(self):

        """

        Implement dispatch interface specified by WSGIController

        """

        try:

            raw_response = self._inspect_call(self._func)

            print raw_response

            if isinstance(raw_response, HTTPError):

                self._error = str(raw_response)

        except JSONRPCError as e:

            self._error = str(e)

        except Exception as e:

            log.debug('Encountered unhandled exception: %s', repr(e))

            json_exc = JSONRPCError('Internal server error')

            self._error = str(json_exc)

        if self._error is not None:

            raw_response = None

        response = dict(result=raw_response, error=self._error)

        try:

            return json.dumps(response)

        except TypeError, e:

            log.debug('Error encoding response: %s', e)

            return json.dumps(dict(result=None,

                                   error="Error encoding response"))

    def _find_method(self):

        """

        Return method named by `self._req_method` in controller if able

        """

        log.debug('Trying to find JSON-RPC method: %s', self._req_method)

        if self._req_method.startswith('_'):

            raise AttributeError("Method not allowed")

        try:

            func = getattr(self, self._req_method, None)

        except UnicodeEncodeError:

            raise AttributeError("Problem decoding unicode in requested "

                                 "method name.")

        if isinstance(func, types.MethodType):

            return func

        else:

            raise AttributeError("No such method: %s" % self._req_method)

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

"""

    rhodecode.lib.__init__

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

    Some simple helper functions

    :created_on: Jan 5, 2011

    :author: marcink

    :copyright: (C) 2009-2010 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, either version 3 of the License, or

# (at your option) any later version.

#

# 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, see <http://www.gnu.org/licenses/>.

try:

    import json

except ImportError:

    #python 2.5 compatibility

    import simplejson as json

def __get_lem():

    from pygments import lexers

    from string import lower

    from collections import defaultdict

    d = defaultdict(lambda: [])

    def __clean(s):

        s = s.lstrip('*')

        s = s.lstrip('.')

        if s.find('[') != -1:

            exts = []

            start, stop = s.find('['), s.find(']')

            for suffix in s[start + 1:stop]:

                exts.append(s[:s.find('[')] + suffix)

            return map(lower, exts)

        else:

            return map(lower, [s])

    for lx, t in sorted(lexers.LEXERS.items()):

        m = map(__clean, t[-2])

        if m:

            m = reduce(lambda x, y: x + y, m)

            for ext in m:

                desc = lx.replace('Lexer', '')

                d[ext].append(desc)

    return dict(d)

# language map is also used by whoosh indexer, which for those specified

# extensions will index it's content

LANGUAGES_EXTENSIONS_MAP = __get_lem()

# Additional mappings that are not present in the pygments lexers

# NOTE: that this will overide any mappings in LANGUAGES_EXTENSIONS_MAP

ADDITIONAL_MAPPINGS = {'xaml': 'XAML'}

LANGUAGES_EXTENSIONS_MAP.update(ADDITIONAL_MAPPINGS)

def str2bool(_str):

    """

    returs True/False value from given string, it tries to translate the

    string into boolean

    :param _str: string value to translate into boolean

    :rtype: boolean

    :returns: boolean from given string

    """

    if _str is None:

        return False

    if _str in (True, False):

        return _str

    _str = str(_str).strip().lower()

    return _str in ('t', 'true', 'y', 'yes', 'on', '1')

def convert_line_endings(line, mode):

    """

    Converts a given line  "line end" accordingly to given mode

    Available modes are::

        0 - Unix

        1 - Mac

        2 - DOS

    :param line: given line to convert

    :param mode: mode to convert to

    :rtype: str

    :return: converted line according to mode

    """

    from string import replace

    if mode == 0:

            line = replace(line, '\r\n', '\n')

            line = replace(line, '\r', '\n')

    elif mode == 1:

            line = replace(line, '\r\n', '\r')

            line = replace(line, '\n', '\r')

    elif mode == 2:

            import re

            line = re.sub("\r(?!\n)|(?<!\r)\n", "\r\n", line)

    return line

def detect_mode(line, default):

    """

    Detects line break for given line, if line break couldn't be found

    given default value is returned

    :param line: str line

    :param default: default

    :rtype: int

    :return: value of line end on of 0 - Unix, 1 - Mac, 2 - DOS

    """

    if line.endswith('\r\n'):

        return 2

    elif line.endswith('\n'):

        return 0

    elif line.endswith('\r'):

        return 1

    else:

        return default

def generate_api_key(username, salt=None):

    """

    Generates unique API key for given username, if salt is not given

    it'll be generated from some random string

    :param username: username as string

    :param salt: salt to hash generate KEY

    :rtype: str

    :returns: sha1 hash from username+salt

    """

    from tempfile import _RandomNameSequence

    import hashlib

    if salt is None:

        salt = _RandomNameSequence().next()

    return hashlib.sha1(username + salt).hexdigest()

    """

    :rtype: unicode

    :returns: unicode object

    """

    try:

    except UnicodeDecodeError:

    """

    :rtype: str

    :returns: str object

    """

    try:

    except UnicodeEncodeError:

    return safe_str

def engine_from_config(configuration, prefix='sqlalchemy.', **kwargs):

    """

    Custom engine_from_config functions that makes sure we use NullPool for

    file based sqlite databases. This prevents errors on sqlite. This only 

    applies to sqlalchemy versions < 0.7.0

    """

    import sqlalchemy

    from sqlalchemy import engine_from_config as efc

    import logging

    if int(sqlalchemy.__version__.split('.')[1]) < 7:

        # This solution should work for sqlalchemy < 0.7.0, and should use

        # proxy=TimerProxy() for execution time profiling

        from sqlalchemy.pool import NullPool

        url = configuration[prefix + 'url']

        if url.startswith('sqlite'):

            kwargs.update({'poolclass': NullPool})

        return efc(configuration, prefix, **kwargs)

    else:

        import time

        from sqlalchemy import event

        from sqlalchemy.engine import Engine

        log = logging.getLogger('sqlalchemy.engine')

        BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE = xrange(30, 38)

        engine = efc(configuration, prefix, **kwargs)

        def color_sql(sql):

            COLOR_SEQ = "\033[1;%dm"

            COLOR_SQL = YELLOW

            normal = '\x1b[0m'

            return ''.join([COLOR_SEQ % COLOR_SQL, sql, normal])

        if configuration['debug']:

            #attach events only for debug configuration

            def before_cursor_execute(conn, cursor, statement,

                                    parameters, context, executemany):

                context._query_start_time = time.time()

                log.info(color_sql(">>>>> STARTING QUERY >>>>>"))

            def after_cursor_execute(conn, cursor, statement,

                                    parameters, context, executemany):

                total = time.time() - context._query_start_time

                log.info(color_sql("<<<<< TOTAL TIME: %f <<<<<" % total))

            event.listen(engine, "before_cursor_execute",

                         before_cursor_execute)

            event.listen(engine, "after_cursor_execute",

                         after_cursor_execute)

    return engine

def age(curdate):

    """

    turns a datetime into an age string.

    :param curdate: datetime object

    :rtype: unicode

    :returns: unicode words describing age

    """

    from datetime import datetime

    from webhelpers.date import time_ago_in_words

    _ = lambda s:s

    if not curdate:

        return ''

    agescales = [(_(u"year"), 3600 * 24 * 365),

                 (_(u"month"), 3600 * 24 * 30),

                 (_(u"day"), 3600 * 24),

                 (_(u"hour"), 3600),

                 (_(u"minute"), 60),

                 (_(u"second"), 1), ]

    age = datetime.now() - curdate

    age_seconds = (age.days * agescales[2][1]) + age.seconds

    pos = 1

    for scale in agescales:

        if scale[1] <= age_seconds:

            if pos == 6:pos = 5

            return '%s %s' % (time_ago_in_words(curdate,

                                                agescales[pos][0]), _('ago'))

        pos += 1

    return _(u'just now')

def uri_filter(uri):

    """

    Removes user:password from given url string

    :param uri:

    :rtype: unicode

    :returns: filtered list of strings  

    """

    if not uri:

        return ''

    proto = ''

    for pat in ('https://', 'http://'):

        if uri.startswith(pat):

            uri = uri[len(pat):]

            proto = pat

            break

    # remove passwords and username

    uri = uri[uri.find('@') + 1:]

    # get the port

    cred_pos = uri.find(':')

    if cred_pos == -1:

        host, port = uri, None

    else:

        host, port = uri[:cred_pos], uri[cred_pos + 1:]

    return filter(None, [proto, host, port])

def credentials_filter(uri):

    """

    Returns a url with removed credentials

    :param uri:

    """

    uri = uri_filter(uri)

    #check if we have port

    if len(uri) > 2 and uri[2]:

        uri[2] = ':' + uri[2]

    return ''.join(uri)

def get_changeset_safe(repo, rev):

    """

    Safe version of get_changeset if this changeset doesn't exists for a 

    repo it returns a Dummy one instead

    :param repo:

    :param rev:

    """

    from vcs.backends.base import BaseRepository

    from vcs.exceptions import RepositoryError

    if not isinstance(repo, BaseRepository):

        raise Exception('You must pass an Repository '

                        'object as first argument got %s', type(repo))

    try:

        cs = repo.get_changeset(rev)

    except RepositoryError:

        from rhodecode.lib.utils import EmptyChangeset

        cs = EmptyChangeset(requested_revision=rev)

    return cs