path: root/hyperkitty/templates/api.html

{% extends "base.html" %}
{% load url from future %}

{% block content %}
    <h2>REST API</h2>
    <p>
        HyperKitty comes with a small REST API allowing you to programatically retrieve 
        emails and information.
    </p>

    <div class="odd" style="padding-left: 1em">
        <h3>Formats</h3>
        <p>
            This REST API can return the information into several formats.
            The default format is html to allow human readibility.<br />
            To change the format, just add 
            <span style="font-style:italic">?format=&lt;FORMAT&gt;</span> to the url
        </p>
        <p>The list of available formats is:</p>
        <ul>
            <li>json <a>(?format=json)</a></li>
            <li>json-p <a>(?format=json-p)</a></li>
            <li>txt <a>(?format=txt)</a></li>
            <li>xml <a>(?format=xml)</a></li>
            <li>html <a>(?format=html)</a></li>
            <li>xhtml <a>(?format=xhtml)</a></li>
        </ul>
    </div>

    <div class="even" style="padding-left: 1em">
        <h3>Lists <a>/api/list/</a></h3>
        <p>
Using the address /api/list/ you will be able to
retrieve the information known about all the mailing-lists.
        </p>
        <p> For example: <a href="{% url 'api_list' %}?format=api">
            {% url 'api_list' %}
        </a>
        </p>
    </div>
    <div class="odd" style="padding-left: 1em">
        <h3>Emails <a>/api/email/&lt;list name&gt;/&lt;Message-ID&gt;</a></h3>
        <p>
Using the address /api/email/&lt;list name&gt;/&lt;Message-ID&gt; you will be able to
retrieve the information known about a specific email on the specified mailing-list.
        </p>
        <p> For example: <a href="{% url 'api_email' mlist_fqdn='devel@fp.o' messageid='13129854572893334' %}?format=api">
            {% url 'api_email' mlist_fqdn='devel@fp.o' messageid='13129854572893334' %}
        </a>
        </p>
    </div>
    <div class="even" style="padding-left: 1em">
        <h3>Threads <a>/api/thread/&lt;list name&gt;/&lt;ThreadID&gt;</a></h3>
        <p>
Using the address /api/thread/&lt;list name&gt;/&lt;Message-ID&gt; you will be able to
retrieve the all the email for a specific thread on the specified mailing-list.
        </p>
        <p> For example: <a href="{% url 'api_thread' mlist_fqdn='devel@fp.o' threadid='13129854572893334' %}?format=api">
            {% url 'api_thread' mlist_fqdn='devel@fp.o' threadid='13129854572893334' %}
        </a>
        </p>
    </div>
        <div class="odd" style="padding-left: 1em">
        <h3>Search <a>/api/search/&lt;list name&gt;/&lt;field&gt;/&lt;keyword&gt;</a></h3>
        <p>
Using the address /api/search/&lt;list name&gt;/&lt;field&gt;/&lt;keyword&gt; you will be able to
search for all emails of the specified mailing-list containing the provided keyword in the given field.
        </p>
        <p>The list of available field is:</p>
        <ul>
            <li>From</li>
            <li>Subject</li>
            <li>Content</li>
            <li>SubjectContent</li>
        </ul>
        <p> For example: <a href="{% url 'api_search' mlist_fqdn='devel@fp.o' field='From' keyword='pingoured' %}?format=api">
            {% url 'api_search' mlist_fqdn='devel@fp.o' field='From' keyword='pingoured' %}
        </a>
        </p>
    </div>
    <div class="even" style="padding-left: 1em">
        <h3>Tags <a>/api/tag/</a></h3>
        <p>
Using the address /api/tag/ you will be able to
retrieve the list of tags.
        </p>
        <p> For example: <a href="{% url 'api_tag' %}?format=api">
            {% url 'api_tag' %}
        </a>
        </p>
    </div>
{% endblock %}