.. _api:

===

API

===

Kallithea has a simple JSON RPC API with a single schema for calling all API

methods. Everything is available by sending JSON encoded http(s) requests to

``<your_server>/_admin/api``.

API access

----------

Clients must send JSON encoded JSON-RPC requests::

    {

        "id: "<id>",

        "api_key": "<api_key>",

        "method": "<method_name>",

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

    }

For example, to pull to a local "CPython" mirror using curl::

    curl https://kallithea.example.com/_admin/api -X POST -H 'content-type:text/plain' \

        --data-binary '{"id":1,"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}'

In general, provide

 - *id*, a value of any type, can be used to match the response with the request that it is replying to.

 - *api_key*, for authentication and permission validation.

 - *method*, the name of the method to call -- a list of available methods can be found below.

 - *args*, the arguments to pass to the method.

.. note::

    api_key can be found or set on the user account page.

The response to the JSON-RPC API call will always be a JSON structure::

    {

        "id": <id>,  # the id that was used in the request

        "result": <result>|null,  # JSON formatted result (null on error)

        "error": null|<error_message>  # JSON formatted error (null on success)

    }

All responses from the API will be ``HTTP/1.0 200 OK``. If an error occurs,

the reponse will have a failure description in *error* and

*result* will be null.

API client

----------

Kallithea comes with a ``kallithea-api`` command line tool, providing a convenient

way to call the JSON-RPC API.

For example, to call ``get_repo``::

    kallithea-api --apihost=<Kallithea URL> --apikey=<API key> get_repo

    Calling method get_repo => <Kallithea URL>

    Server response

    ERROR:"Missing non optional `repoid` arg in JSON DATA"

Oops, looks like we forgot to add an argument. Let's try again, now

providing the ``repoid`` as a parameter::

    kallithea-api --apihost=<Kallithea URL> --apikey=<API key> get_repo repoid:myrepo

    Calling method get_repo => <Kallithea URL>

    Server response

    {

        "clone_uri": null,

        "created_on": "2015-08-31T14:55:19.042",

    ...

To avoid specifying ``apihost`` and ``apikey`` every time, run::

    kallithea-api --save-config --apihost=<Kallithea URL> --apikey=<API key>

This will create a ``~/.config/kallithea`` with the specified URL and API key

so you don't have to specify them every time.

API methods

-----------

pull

^^^^

Pull the given repo from remote location. Can be used to automatically keep

remote repos up to date.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "pull"

    args :    {

                "repoid" : "<reponame or repo_id>"

              }

OUTPUT::

<table class="table">

    <tr>

        <td style="width: 450px"><div class="truncate autoexpand" style="width:120px;font-size:16px;font-family: monospace">${c.user.api_key}</div></td>

        <td>

            <span class="label label-success">${_('Built-in')}</span>

        </td>

        <td>${_('Expires')}: ${_('Never')}</td>

        <td>

            ${h.form(url('my_account_api_keys_delete'))}

                ${h.hidden('del_api_key',c.user.api_key)}

                ${h.hidden('del_api_key_builtin',1)}

                <button class="btn btn-danger btn-xs" type="submit"

                        onclick="return confirm('${_('Confirm to reset this API key: %s') % c.user.api_key}');">

                    ${_('Reset')}

                </button>

            ${h.end_form()}

        </td>

    </tr>

    %if c.user_api_keys:

        %for api_key in c.user_api_keys:

          <tr class="${'expired' if api_key.is_expired else ''}">

            <td style="width: 450px"><div class="truncate autoexpand" style="width:120px;font-size:16px;font-family: monospace">${api_key.api_key}</div></td>

            <td>${api_key.description}</td>

            <td style="min-width: 80px">

                 %if api_key.expires == -1:

                  ${_('Expires')}: ${_('Never')}

                 %else:

                    %if api_key.is_expired:

                        ${_('Expired')}: ${h.age(h.time_to_datetime(api_key.expires))}

                    %else:

                        ${_('Expires')}: ${h.age(h.time_to_datetime(api_key.expires))}

                    %endif

                 %endif

            </td>

            <td>

                ${h.form(url('my_account_api_keys_delete'))}

                    ${h.hidden('del_api_key',api_key.api_key)}

                    <button class="btn btn-danger btn-xs" type="submit"

                            onclick="return confirm('${_('Confirm to remove this API key: %s') % api_key.api_key}');">

                        <i class="icon-minus-circled"></i>

                        ${_('Remove')}

                    </button>

                ${h.end_form()}

            </td>

          </tr>

        %endfor

    %else:

    <tr><td><div class="ip">${_('No additional API keys specified')}</div></td></tr>

    %endif

</table>

<div>

    ${h.form(url('my_account_api_keys'), method='post')}

    <div class="form">

        <div class="form-horizontal">

            <div class="form-group">

                <label class="control-label">${_('New API key')}</label>

            </div>

            <div class="form-group">

                <label class="control-label" for="description">${_('Description')}:</label>

                <div>

                    ${h.text('description', class_='form-control', placeholder=_('Description'))}

                </div>

            </div>

            <div class="form-group">

                <label class="control-label" for="lifetime">${_('Lifetime')}:</label>

                <div>

                    ${h.select('lifetime', '', c.lifetime_options)}

                </div>

            </div>

            <div class="form-group">

                <div class="buttons">

                    ${h.submit('save',_('Add'),class_="btn btn-default")}

                    ${h.reset('reset',_('Reset'),class_="btn btn-default")}

                </div>

            </div>

        </div>

    </div>

    ${h.end_form()}

</div>

<script>

    $(document).ready(function(){

        $("#lifetime").select2({

            'dropdownAutoWidth': true

        });

    });

</script>