django-helpdesk/helpdesk/templates/helpdesk/help_api.html

{% extends "helpdesk/help_base.html" %}{% load url from future %}

{% block title %}django-helpdesk API Documentation{% endblock %}
{% block heading %}django-helpdesk API Documentation{% endblock %}

{% block content %}
        <h2>Contents</h2>

        <ul>
            <li><a href='#introduction'>Introduction</a></li>
            <li><a href='#request'>Request Basics &amp; Authentication</a></li>
            <li><a href='#response'>Responses</a></li>
            <li><a href='#methods'>Method Documentation</a>
                <ul>
                    <li><a href='#method_create_ticket'>create_ticket</a></li>
                    <li><a href='#method_delete_ticket'>delete_ticket</a></li>
                    <li><a href='#method_hold_ticket'>hold_ticket</a></li>
                    <li><a href='#method_unhold_ticket'>unhold_ticket</a></li>
                    <li><a href='#method_add_followup'>add_followup</a></li>
                    <li><a href='#method_resolve'>resolve</a></li>
                    <li><a href='#method_list_queues'>list_queues</a></li>
                    <li><a href='#method_find_user'>find_user</a></li>
                </ul>
            </li>
        </ul>

        <h2 id='introduction'>Introduction</h2>

        <p>django-helpdesk provides a powerful <acronym title='Application Programming Interface'>API</acronym> to allow you to interact with your helpdesk tickets by a means not otherwise provided by the helpdesk.</p>

        <p>For example, you may use this API to implement a system to automatically open a ticket when an invoice is raised in your invoicing system, or to automatically close a ticket from an instant messenger application.</p>

        <p>Your use of this system is open-ended: most business cases should be addressible with a little bit of coding to allow you to interact nicely with your helpdesk.</p>

        <h2 id='request'>Request Basics &amp; Authentication</h2>

        <p>All requests to the API must be made using <acroynm title='HyperText Transfer Protocol'>HTTP</acronym> POST requests. Any request that is not made using POST will raise an error.</p>

        <p>Your requests must be made up of the following elements:</p>

        <ol>
            <li>A <em>method</em>, or action. This tells the API what core functionality to execute.</li>
            <li>A <em>username</em> and <em>password</em> which are valid and active within your helpdesk system. You may wish to create a specific API user just for API usage.</li>
            <li>A set of <em>data</em> to be saved into the database. This data will vary from request to request, and is outlined in <a href='#methods'>Methods</a> below.</li>
        </ol>

        <p>To build your request, send a HTTP POST request to <em>{% url 'helpdesk_api' "method" %}</em>, where <em>method</em> is the name of a <a href='#methods'>valid method</a> from the list below.</p>

        <p>Your POST must include both <em>user</em> and <em>password</em> parameters.</p>

        <p>A sample request for the method <em>hold_ticket</em> may look like this:</p>

        <ul>
            <li>A HTTP POST to <em>{% url 'helpdesk_api' "hold_ticket" %}</em></li>
            <li>A set of POST data containing:<ul>
                <li>username=susan</li>
                <li>password=fido</li>
                <li>ticket=31794</li>
            </ul></li>
        </ul>

        <p>To complete this from a command-line using the <a href='http://curl.haxx.se/'>cURL</a> application, you may use a command such as this:</p>

        <pre>/usr/bin/curl {% url 'helpdesk_api' "hold_ticket" %} --data "user=susan&amp;password=fido&amp;ticket=31794"</pre>

        <p>In <a href='http://www.php.net/'>PHP</a>, providing you have access to the <a href='http://www.php.net/curl'>cURL libraries</a>, you may use code such as this:</p>

        <pre>&lt;?php
$api = curl_init();
curl_setopt($api, CURLOPT_URL, "{% url 'helpdesk_api' "hold_ticket" %}");
curl_setopt($api, CURLOPT_POST, 1);
curl_setopt($api, CURLOPT_POSTFIELDS, "user=susan&amp;password=fido&amp;ticket=31794");
$result = curl_exec($api);
curl_close($api);
echo $result;
?&gt;</pre>

        <p>Note that cURL expects all data to be urlencoded, this is left as an exercise for the reader.</p>

        <h2 id='response'>Responses</h2>

        <p>The API system makes proper use of the following HTTP response codes:</p>

        <dl>
            <dt>200</dt>
            <dd>OK - Data updated successfully</dd>

            <dt>400</dt>
            <dd>ERROR - Generic error. See returned text for details</dd>

            <dt>404</dt>
            <dd>ERROR - Data not found (eg, incorrect ticket). See returned text for details</dd>

            <dt>403</dt>
            <dd>ERROR - Invalid permissions (eg, incorrect username and/or password)</dd>

            <dt>405</dt>
            <dd>ERROR - Invalid method. You probably tried using GET, PUT or DELETE however we require POST.</dd>
        </dl>

        <p>Responses will have one of two content-types:</p>
        
        <dl>
            <dt>text/plain</dt>
            <dd>Any error messages, or simple responses (eg a ticket ID)</dd>

            <dt>text/json</dt>
            <dd>Any complex responses, such as a list of data.</dd>
        </dl>

        <h2 id='methods'>Method Documentation</h2>

        <p>The following public methods are available for use via the API. Each of them requires <a href='#request'>a valid request and authentication</a>, and each has it's own parameters as described below.</p>

        <ul>
            <li><a href='#method_create_ticket'>create_ticket</a></li>
            <li><a href='#method_delete_ticket'>delete_ticket</a></li>
            <li><a href='#method_hold_ticket'>hold_ticket</a></li>
            <li><a href='#method_unhold_ticket'>unhold_ticket</a></li>
            <li><a href='#method_add_followup'>add_followup</a></li>
            <li><a href='#method_resolve'>resolve</a></li>
            <li><a href='#method_list_queues'>list_queues</a></li>
            <li><a href='#method_find_user'>find_user</a></li>
        </ul>

        <h3 id='method_create_ticket'>create_ticket</h3>

        <p>This method creates a new helpdesk ticket.</p>

        <h4>Parameters</h4>

        <dl>
            <dt>queue</dt>
            <dd>Queue ID (use <a href='#method_list_queues'>list_queues</a> to get queue ID's) - this is an integer field.</dd>

            <dt>title</dt>
            <dd>Title or header of this ticket. Character field, maximum 100 characters.</dd>

            <dt>submitter_email</dt>
            <dd>(Optional) e-mail address of the person submitting this ticket. This e-mail address will receive copies of all public updates to this ticket, and will receive a notification when the ticket is created.</dd>

            <dt>assigned_to</dt>
            <dd>(Optional) Integer ID of the user to which this ticket should be assigned. Use <a href='#method_find_user'>find_user</a> to find a user ID from a username.</dd>

            <dt>priority</dt>
            <dd>(Optional) Priority as an integer from 1 (high) to 5 (low). Defaults to 3 if no priority given.</dd>
        </dl>

        <h4>Response</h4>

        <p>This method responds with <strong>plain-text</strong>.</p>

        <p>If you receive a 200 OK <a href='#response'>response</a>, then the content of the response will be the ticket ID.</p>
        
        <h3 id='method_delete_ticket'>delete_ticket</h3>

        <p>When given a ticket ID and confirmation, this method will delete a ticket entirely. This also deletes any followups, attachments, and other details.</p>

        <h4>Parameters</h4>

        <dl>
            <dt>ticket</dt>
            <dd>The numeric ticket ID to be deleted</dd>

            <dt>confirm</dt>
            <dd>You must provide this field, with any value, to enable deletion to continue</dd>
        </dl>

        <h4>Response</h4>

        <p>A standard <a href='#response'>200 OK response</a> is given on success, or an error message on failure.</p>

        <h3 id='method_hold_ticket'>hold_ticket</h3>

        <p>If a ticket needs to be placed on hold, preventing it from being escalated, use this method.</p>

        <h4>Parameters</h4>
        <dl>
            <dt>ticket</dt>
            <dd>The numeric ticket ID to be placed on hold</dd>
        </dl>

        <h4>Response</h4>
        
        <p>A standard <a href='#response'>200 OK response</a> is given on success, or an error message on failure.</p>

        
        <h3 id='method_unhold_ticket'>unhold_ticket</h3>

        <p>If a ticket is currently on hold and you wish to remove that hold, use this method.</p>

        <h4>Parameters</h4>
        <dl>
            <dt>ticket</dt>
            <dd>The numeric ticket ID to be taken off hold</dd>
        </dl>

        <h4>Response</h4>
        
        <p>A standard <a href='#response'>200 OK response</a> is given on success, or an error message on failure.</p>
        
        
        <h3 id='method_add_followup'>add_followup</h3>

        <p>This method adds a comment / followup to a ticket. The followup can be public, in which case it is e-mailed to the submitter, or private. The followup will also be sent to others involved in the ticket: The owner and the queue notification / CC address.</p>

        <h4>Parameters</h4>

        <dl>
            <dt>ticket</dt>
            <dd>The numeric ticket ID to which this followup should be added</dd>

            <dt>message</dt>
            <dd>Text of 'unlimited' length - optionally formatted with HTML - to add to the message.</dd>

            <dt>public</dt>
            <dd>Either 'y' for public, or 'n' for private. This is optional, and it is assumed that followups are private if it is not provided. Private tickets are <strong>not</strong> e-mailed to the ticket submitter.</dd>
        </dl>

        <h4>Response</h4>

        <p>A standard <a href='#response'>200 OK response</a> is given on success, or an error message on failure.</p>
        
        
        <h3 id='method_resolve'>resolve</h3>
        
        <p>This method adds a resolution to a ticket and marks it as resolved. The resolution will be e-mailed to everybody involved with the ticket, including the submitter.</p>

        <h4>Parameters</h4>

        <dl>
            <dt>ticket</dt>
            <dd>The numeric ticket ID to which this followup should be added</dd>

            <dt>resolution</dt>
            <dd>Text of 'unlimited' length - optionally formatted with HTML. This is the resolution for this ticket.</dd>
        </dl>

        <h4>Response</h4>

        <p>A standard <a href='#response'>200 OK response</a> is given on success, or an error message on failure.</p>
        
        
        <h3 id='method_list_queues'>list_queues</h3>

        <p>This method provides a JSON-parsable list of queues, letting you access the individual queue ID in order to create tickets.</p>

        <h4>Response</h4>

        <p>This method responds with <strong>json</strong>.</p>
        
        <p>It provides a list of queues in JSON format. The fields provided are ID and Title.</p>

        
        <h3 id='method_find_user'>find_user</h3>

        <p>When given a username, this method provides the related numeric user ID - commonly used when creating or reassigning tickets.</p>
        
        <h4>Parameters</h4>

        <dl>
            <dt>username</dt>
            <dd>The case-sensitive username of the user for which you require the user ID</dd>
        </dl>
        
        <h4>Response</h4>

        <p>This method responds with <strong>plain-text</strong>.</p>

        <p>If you receive a 200 OK <a href='#response'>response</a>, then the content of the response will be the users ID.</p>
{% endblock %}