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

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