From ca1690becb9e3b1a31419638f22e9178e42f04e6 Mon Sep 17 00:00:00 2001
From: Ross Poulton <ross@rossp.org>
Date: Tue, 22 Dec 2015 11:28:00 +1100
Subject: [PATCH] Deprecate custom API (see #198)

---
 docs/api.rst                              |  6 ++++--
 helpdesk/templates/helpdesk/base.html     |  2 +-
 helpdesk/templates/helpdesk/help_api.html |  6 ++++++
 helpdesk/views/api.py                     | 10 +++++++++-
 4 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index d26bc215..f7f6404b 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -1,6 +1,8 @@
 Ticket API
 ==========
 
-django-helpdesk includes an API accessible via HTTP POST requests, allowing you to create and alter tickets from 3rd party software and systems.
+*Warning*: The django-helpdesk API is deprecated, and no longer maintained. See https://github.com/rossp/django-helpdesk/issues/198 for more details.
 
-For usage instructions and command syntax, see the file ``templates/helpdesk/api_help.html``, or visit http://helpdesk/api/help/.
+The API will be removed in January 2016 - you should instead build an integration with eg django-rest-framework.
+
+For details on the current API including usage instructions and command syntax, see the file ``templates/helpdesk/api_help.html``, or visit http://helpdesk/api/help/.
diff --git a/helpdesk/templates/helpdesk/base.html b/helpdesk/templates/helpdesk/base.html
index 433c825c..d5dcd2f2 100644
--- a/helpdesk/templates/helpdesk/base.html
+++ b/helpdesk/templates/helpdesk/base.html
@@ -60,7 +60,7 @@
             <div id='footer' class="row">
                 <div class="col-md-2">{% include "helpdesk/attribution.html" %}</div>
                 <div class="col-md-2"><a href='{% url 'helpdesk_rss_index' %}'><img src='{% static "helpdesk/rss_icon.png" %}' width='14' height='14' alt='{% trans "RSS Icon" %}' title='{% trans "RSS Feeds" %}' border='0' />{% trans "RSS Feeds" %}</a></div>
-                <div class="col-md-2"><a href='{% url 'helpdesk_api_help' %}'>{% trans "API" %}</a></div>
+                <div class="col-md-2"><s><a href='{% url 'helpdesk_api_help' %}'>{% trans "API" %}</a></s></div>
                 {% if user.is_superuser %}<div class="col-md-2"><a href='{% url 'helpdesk_system_settings' %}'>{% trans "System Settings" %}</a></div>{% endif %}
             </div>
         </div>
diff --git a/helpdesk/templates/helpdesk/help_api.html b/helpdesk/templates/helpdesk/help_api.html
index bcb7cb92..a73ca5a9 100644
--- a/helpdesk/templates/helpdesk/help_api.html
+++ b/helpdesk/templates/helpdesk/help_api.html
@@ -23,6 +23,12 @@
                 </ul>
             </li>
         </ul>
+        <h2 id='warning'>Deprecation Warning</h2>
+
+        <P>This API has been deprecated and will be removed in January 2016. Please <a href='https://github.com/rossp/django-helpdesk/issues/198'>See the GitHub Issue Tracker</a> for more details.</p>
+        <P>Do <strong>not</strong> build new integrations using this API.</p>
+
+        <p>We recommend using django-rest-framework or similar for all integrations.</p>
 
         <h2 id='introduction'>Introduction</h2>
 
diff --git a/helpdesk/views/api.py b/helpdesk/views/api.py
index bb80e701..08bb4991 100644
--- a/helpdesk/views/api.py
+++ b/helpdesk/views/api.py
@@ -33,6 +33,8 @@ from helpdesk.forms import TicketForm
 from helpdesk.lib import send_templated_mail, safe_template_context
 from helpdesk.models import Ticket, Queue, FollowUp
 
+import warnings
+
 STATUS_OK = 200
 
 STATUS_ERROR = 400
@@ -53,8 +55,14 @@ def api(request, method):
           must be valid users
         * The method must match one of the public methods of the API class.
 
+
+    THIS IS DEPRECATED AS OF DECEMBER 2015 AND WILL BE REMOVED IN JANUARY 2016.
+    SEE https://github.com/rossp/django-helpdesk/issues/198 FOR DETAILS
+
     """
 
+    warnings.warn("django-helpdesk API will be removed in January 2016. See https://github.com/rossp/django-helpdesk/issues/198 for details.", category=DeprecationWarning)
+
     if method == 'help':
         return render_to_response('helpdesk/help_api.html')
 
@@ -330,4 +338,4 @@ class API:
 
         ticket.save()
 
-        return api_return(STATUS_OK)
\ No newline at end of file
+        return api_return(STATUS_OK)