.. _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 web view in RhodeCode that is 

decorated with `@LoginRequired` decorator. To enable API access simple change 

the standard login decorator to `@LoginRequired(api_access=True)`. 

After this change, a rhodecode view can be accessed without login by adding a 

GET parameter `?api_key=<api_key>` to url. By default this is only

enabled on RSS/ATOM feed views.

API ACCESS

++++++++++

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

.. _models:

The :mod:`models` Module

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

.. automodule:: rhodecode.model

   :members:

.. automodule:: rhodecode.model.comment

   :members:

.. automodule:: rhodecode.model.notification

   :members:   

.. automodule:: rhodecode.model.permission

   :members:

.. automodule:: rhodecode.model.repo_permission

   :members:      

.. automodule:: rhodecode.model.repo

   :members:   

.. automodule:: rhodecode.model.repos_group

   :members:

.. _changelog:

Changelog

=========

1.3.4 (**2012-XX-XX**)

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

:status: in-progress

:branch: beta

news

++++

fixes

+++++

1.3.3 (**2012-03-02**)

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

news

++++

.. _contributing:

Contributing to RhodeCode

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

If you would like to contribute to RhodeCode, please contact me, any help is

greatly appreciated!

Could I request that you make your source contributions by first forking the

RhodeCode repository on bitbucket_

https://bitbucket.org/marcinkuzminski/rhodecode and then make your changes to

your forked repository. Please post all fixes into **BETA** branch since your 

fix might be already fixed there and i try to merge all fixes from beta into

stable, and not the other way. Finally, when you are finished making a change, 

please send me a pull request.

To run RhodeCode in a development version you always need to install the latest

required libs from `requires.txt` file.

after downloading/pulling RhodeCode make sure you run::

    python setup.py develop

command to install/verify all required packages, and prepare development 

enviroment.

.. _installation:

Installation

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

``RhodeCode`` is written entirely in Python. Before posting any issues make 

sure, your not missing any system libraries and using right version of 

libraries required by RhodeCode. There's also restriction in terms of mercurial

clients. Minimal version of hg client known working fine with RhodeCode is

**1.6**. If you're using older client, please upgrade.

Installing RhodeCode from Cheese Shop

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

Rhodecode requires python version 2.5 or higher.

The easiest way to install ``rhodecode`` is to run::

    easy_install rhodecode

Or::

    pip install rhodecode

If you prefer to install RhodeCode manually simply grab latest release from

.. _setup:

Setup

=====

Setting up RhodeCode

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

First, you will need to create a RhodeCode configuration file. Run the 

following command to do this::

    paster make-config RhodeCode production.ini

- This will create the file `production.ini` in the current directory. This

  configuration file contains the various settings for RhodeCode, e.g proxy 

  port, email settings, usage of static files, cache, celery settings and 

  logging.

Next, you need to create the databases used by RhodeCode. I recommend that you

use sqlite (default) or postgresql. If you choose a database other than the

default ensure you properly adjust the db url in your production.ini

configuration file to use this other database. Create the databases by running

the following command::

.. _upgrade:

Upgrade

=======

Upgrading from Cheese Shop

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

.. note::

   Firstly, it is recommended that you **always** perform a database backup 

   before doing an upgrade.

The easiest way to upgrade ``rhodecode`` is to run::

 easy_install -U rhodecode

Or::

 pip install --upgrade rhodecode

Then make sure you run the following command from the installation directory::

 paster make-config RhodeCode production.ini

This will display any changes made by the new version of RhodeCode to your

.. _backup:

Backing up RhodeCode

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

Settings

--------

Just copy your .ini file, it contains all RhodeCode settings.

Whoosh index

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

Whoosh index is located in **/data/index** directory where you installed

RhodeCode ie. the same place where the ini file is located

Database

--------

When using sqlite just copy rhodecode.db.

Any other database engine requires a manual backup operation.

Database backup will contain all gathered statistics

.. _general:

General RhodeCode usage

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

Repository deleting

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

Currently when admin/owner deletes a repository, RhodeCode does not physically

delete a repository from filesystem, it renames it in a special way so it's

not possible to push,clone or access repository. It's worth a notice that,

even if someone will be given administrative access to RhodeCode and will 

delete a repository You can easy restore such action by restoring `rm__<date>`

from the repository name, and internal repository storage (.hg/.git)

Follow current branch in file view

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

In file view when this checkbox is checked the << and >> arrows will jump

to changesets within the same branch currently viewing. So for example

if someone is viewing files at 'beta' branch and marks `follow current branch`

checkbox the << and >> buttons will only show him revisions for 'beta' branch

Compare view from changelog

.. _git_support:

GIT support

===========

Git support in RhodeCode 1.3 was enabled by default. 

Although There are some limitations on git usage.

- No hooks are runned for git push/pull actions.

- logs in action journals don't have git operations

- large pushes needs http server with chunked encoding support.

if you plan to use git you need to run RhodeCode with some

http server that supports chunked encoding which git http protocol uses, 

i recommend using waitress_ or gunicorn_ (linux only) for `paste` wsgi app 

replacement.

To use waitress simply change change the following in the .ini file::

    use = egg:Paste#http

To::

    use = egg:waitress#main

.. _statistics:

Statistics

==========

The RhodeCode statistics system makes heavy demands of the server resources, so

in order to keep a balance between usability and performance, the statistics are

cached inside db and are gathered incrementally, this is how RhodeCode does

this:

With Celery disabled

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

- On each first visit to the summary page a set of 250 commits are parsed and

  updates statistics cache.

- This happens on each single visit to the statistics page until all commits are

  fetched. Statistics are kept cached until additional commits are added to the

  repository. In such a case RhodeCode will only fetch the new commits when

  updating it's cache.

With Celery enabled

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

- On the first visit to the summary page RhodeCode will create tasks that will

  execute on celery workers. This task will gather all of the stats until all