.. _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 to 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)`.

To make this operation easier, starting from version 1.7.0 there's a white list

of views that will have API access enabled. Simply edit `api_access_controllers_whitelist`

option in your .ini file, and define views that should have API access enabled.

Following example shows how to enable API access to patch/diff raw file and archive

in RhodeCode::

        ChangesetController:changeset_patch,

        ChangesetController:changeset_raw,

        FilesController:raw,

        FilesController:archivefile

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. Exposing raw diffs is a good way to integrate with

3rd party services like code review, or build farms that could download archives.

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>, # matching id sent by request

        "result": "<result>"|null, # JSON formatted result, null if any errors

        "error": "null"|<error_message> # JSON formatted error (if any)

    }

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

Mails are also sent for code comments. If someone comments on a changeset

mail is sent to all participants, the person who commited the changeset

(if present in RhodeCode), and to all people mentioned with @mention system.

Trending source files

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

Trending source files are calculated based on pre defined dict of known

types and extensions. If You miss some extension or Would like to scan some

custom files it's possible to add new types in `LANGUAGES_EXTENSIONS_MAP` dict

located in `/rhodecode/lib/celerylib/tasks.py`

Cloning remote repositories

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

RhodeCode has an ability to clone remote repos from given remote locations.

Currently it support following options:

- hg  -> hg clone

- svn -> hg clone

- git -> git clone

.. note::

    - *`svn -> hg` cloning requires `hgsubversion` library to be installed.*

If you need to clone repositories that are protected via basic auth, you

might pass the url with stored credentials inside eg.

`http://user:passw@remote.server/repo`, RhodeCode will try to login and clone

using given credentials. Please take a note that they will be stored as

plaintext inside the database. RhodeCode will remove auth info when showing the

clone url in summary page.

Visual settings in admin pannel

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

Visualisation settings in RhodeCode settings view are extra customizations

of server behavior. There are 3 main section in the settings.

General

~~~~~~~

`Use repository extra fields` option allows to set a custom fields for each

repository in the system. Each new field consists of 3 attributes `field key`,

`field label`, `field description`. Example usage of such fields would be to

define company specific information into repositories eg. defining repo_manager

key that would add give info about a manager of each repository. There's no

limit for adding custom fields. Newly created fields are accessible via API.

Icons

~~~~~

Show public repo icon / Show private repo icon on repositories - defines if

public/private icons should be shown in the UI.

Meta-Tagging

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

With this option enabled, special metatags that are recognisible by RhodeCode

will be turned into colored tags. Currently available tags are::

    [featured]

    [stale]

    [dead]

    [lang => lang]

    [license => License]

    [requires => Repo]

    [recommends => Repo]

    [see => URI]