.. _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

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

    {

        "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 '{"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}'

Simply provide

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

    {

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

              }

OUTPUT::

    result : "Pulled from <repo_name>"

    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

-----------

Creates new user or updates current one if such user exists. This command can 

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

INPUT::

    api_key : "<api_key>"

API Reference

=============

.. toctree::

   :maxdepth: 3

   models

   api 

.. _changelog:

Changelog

=========

1.2.3 (**2011-11-02**)

======================

news

----

- added option to manage repos group for non admin users

- added following API methods for get_users, create_user, get_users_groups, 

  get_users_group, create_users_group, add_user_to_users_groups, get_repos, 

  get_repo, create_repo, add_user_to_repo

- implements #237 added password confirmation for my account 

  and admin edit user.

- implements #291 email notification for global events are now sent to all

  administrator users, and global config email.

fixes

-----

- added option for passing auth method for smtp mailer

- #276 issue with adding a single user with id>10 to usergroups

- #277 fixes windows LDAP settings in which missing values breaks the ldap auth 

- #288 fixes managing of repos in a group for non admin user

1.2.2 (**2011-10-17**)

======================

news

----

- #226 repo groups are available by path instead of numerical id

fixes

-----

- #259 Groups with the same name but with different parent group

- #260 Put repo in group, then move group to another group -> repo becomes unavailable

- #258 RhodeCode 1.2 assumes egg folder is writable (lockfiles problems)

- #265 ldap save fails sometimes on converting attributes to booleans, 

  added getter and setter into model that will prevent from this on db model level

- fixed problems with timestamps issues #251 and #213

- fixes #266 RhodeCode allows to create repo with the same name and in 

  the same parent as group

- fixes #245 Rescan of the repositories on Windows

- fixes #248 cannot edit repos inside a group on windows

- fixes #219 forking problems on windows

1.2.1 (**2011-10-08**)

======================

news

----

fixes

-----

- fixed problems with basic auth and push problems 

- gui fixes

- fixed logger

1.2.0 (**2011-10-07**)

======================

news

----

- implemented #47 repository groups

- implemented #89 Can setup google analytics code from settings menu

- implemented #91 added nicer looking archive urls with more download options

  like tags, branches

- implemented #44 into file browsing, and added follow branch option

- implemented #84 downloads can be enabled/disabled for each repository

- anonymous repository can be cloned without having to pass default:default

  into clone url

- fixed #90 whoosh indexer can index chooses repositories passed in command 

  line

- extended journal with day aggregates and paging

- implemented #107 source code lines highlight ranges

- implemented #93 customizable changelog on combined revision ranges - 

  equivalent of githubs compare view 

- implemented #108 extended and more powerful LDAP configuration

- implemented #56 users groups

- major code rewrites optimized codes for speed and memory usage

- raw and diff downloads are now in git format

- setup command checks for write access to given path

- fixed many issues with international characters and unicode. It uses utf8

  decode with replace to provide less errors even with non utf8 encoded strings

- #125 added API KEY access to feeds

- #109 Repository can be created from external Mercurial link (aka. remote 

  repository, and manually updated (via pull) from admin panel

- beta git support - push/pull server + basic view for git repos

- added followers page and forks page

- server side file creation (with binary file upload interface) 

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

"""

    rhodecode.__init__

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

    RhodeCode, a web based repository management based on pylons

    versioning implementation: http://semver.org/

    :created_on: Apr 9, 2010

    :author: marcink

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

import platform

VERSION = (1, 2, 4)

__version__ = '.'.join((str(each) for each in VERSION[:4]))

__dbversion__ = 3  # defines current db version for migrations

__platform__ = platform.system()

__license__ = 'GPLv3'

PLATFORM_WIN = ('Windows')

PLATFORM_OTHERS = ('Linux', 'Darwin', 'FreeBSD', 'OpenBSD', 'SunOS')

try:

    from rhodecode.lib import get_current_revision

    _rev = get_current_revision(quiet=True)

except ImportError:

    _rev = False

if len(VERSION) > 3 and _rev:

    __version__ += ' [rev:%s]' % _rev[0]

def get_version():

    """Returns shorter version (digit parts only) as string."""

    return '.'.join((str(each) for each in VERSION[:3]))

BACKENDS = {

    'hg': 'Mercurial repository',

    #'git': 'Git repository',

}

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

"""

    rhodecode.lib.__init__

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

    Some simple helper functions

    :created_on: Jan 5, 2011

    :author: marcink

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

import os

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

def safe_unicode(str_, from_encoding='utf8'):

    """

    safe unicode function. Does few trick to turn str_ into unicode

    In case of UnicodeDecode error we try to return it with encoding detected

    by chardet library if it fails fallback to unicode with errors replaced

    :param str_: string to decode

    :rtype: unicode

    :returns: unicode object

    """

    if isinstance(str_, unicode):

        return str_

    try:

        return unicode(str_)

    except UnicodeDecodeError:

        pass

    try:

        return unicode(str_, from_encoding)

    except UnicodeDecodeError:

        pass

    try:

        import chardet

        encoding = chardet.detect(str_)['encoding']

        if encoding is None:

            raise Exception()

        return str_.decode(encoding)

    except (ImportError, UnicodeDecodeError, Exception):

        return unicode(str_, from_encoding, 'replace')

def safe_str(unicode_, to_encoding='utf8'):

    """

    safe str function. Does few trick to turn unicode_ into string

    In case of UnicodeEncodeError we try to return it with encoding detected

    by chardet library if it fails fallback to string with errors replaced

    :param unicode_: unicode to encode

    :rtype: str

    :returns: str object

    """

    if not isinstance(unicode_, basestring):

        return str(unicode_)

    if isinstance(unicode_, str):

        return unicode_

    try:

        return unicode_.encode(to_encoding)

    except UnicodeEncodeError:

        pass

    try:

        import chardet

        encoding = chardet.detect(unicode_)['encoding']

        print encoding

        if encoding is None:

            raise UnicodeEncodeError()

        return unicode_.encode(encoding)

    except (ImportError, UnicodeEncodeError):

        return unicode_.encode(to_encoding, 'replace')

    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)

import sys

from rhodecode import get_version

from rhodecode import __platform__

from rhodecode import __license__

from rhodecode import PLATFORM_OTHERS

py_version = sys.version_info

if py_version < (2, 5):

    raise Exception('RhodeCode requires python 2.5 or later')

dependency_links = [

]

classifiers = ['Development Status :: 5 - Production/Stable',

               'Environment :: Web Environment',

               'Framework :: Pylons',

               'Intended Audience :: Developers',

               'License :: OSI Approved :: GNU General Public License (GPL)',

               'Operating System :: OS Independent',

               'Programming Language :: Python',

               'Programming Language :: Python :: 2.5',

               'Programming Language :: Python :: 2.6',

               'Programming Language :: Python :: 2.7', ]

if py_version < (2, 6):

    requirements.append("simplejson")

    requirements.append("pysqlite")

if __platform__ in PLATFORM_OTHERS:

    requirements.append("py-bcrypt")

# additional files from project that goes somewhere in the filesystem

# relative to sys.prefix

data_files = []

# additional files that goes into package itself

package_data = {'rhodecode': ['i18n/*/LC_MESSAGES/*.mo', ], }

description = ('Mercurial repository browser/management with '

               'build in push/pull server and full text search')

keywords = ' '.join(['rhodecode', 'rhodiumcode', 'mercurial', 'git',

                     'code review', 'repo groups', 'ldap'

                      'repository management', 'hgweb replacement'

                      'hgwebdir', 'gitweb replacement', 'serving hgweb', ])

# long description

try:

    readme_file = 'README.rst'

    changelog_file = 'docs/changelog.rst'

    long_description = open(readme_file).read() + '\n\n' + \

        open(changelog_file).read()

except IOError, err:

    sys.stderr.write("[WARNING] Cannot find file specified as "

        "long_description (%s)\n or changelog (%s) skipping that file" \

            % (readme_file, changelog_file))

    long_description = description

try:

    from setuptools import setup, find_packages

except ImportError:

    from ez_setup import use_setuptools

    use_setuptools()

    from setuptools import setup, find_packages

# packages

packages = find_packages(exclude=['ez_setup'])

setup(

    name='RhodeCode',

    version=get_version(),

    description=description,

    long_description=long_description,

    keywords=keywords,

    license=__license__,

    author='Marcin Kuzminski',

    author_email='marcin@python-works.com',

    dependency_links=dependency_links,

    url='http://rhodecode.org',

    install_requires=requirements,

    classifiers=classifiers,

    setup_requires=["PasteScript>=1.6.3"],

    data_files=data_files,

    packages=packages,

    include_package_data=True,

    test_suite='nose.collector',

    package_data=package_data,

    message_extractors={'rhodecode': [

            ('**.py', 'python', None),

            ('templates/**.mako', 'mako', {'input_encoding': 'utf-8'}),

            ('templates/**.html', 'mako', {'input_encoding': 'utf-8'}),

            ('public/**', 'ignore', None)]},

    zip_safe=False,

    paster_plugins=['PasteScript', 'Pylons'],

    entry_points="""

    [paste.app_factory]

    main = rhodecode.config.middleware:make_app

    [paste.app_install]

    main = pylons.util:PylonsInstaller

    [paste.global_paster_command]

    make-index = rhodecode.lib.indexers:MakeIndex

    upgrade-db = rhodecode.lib.dbmigrate:UpgradeDb

    celeryd=rhodecode.lib.celerypylons.commands:CeleryDaemonCommand