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

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

# -*- 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: [])

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

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:

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