Add an API section in documentation + fix small things

docs/api.rst

@@ -0,0 +1,59 @@
+API
+===
+
+A REST API (built with ``djangorestframework``) is available in order to list, create, update and delete tickets from other tools thanks to HTTP requests.
+
+You must be authenticated to access the API, the URL endpoint is ``/api/tickets/``. You can configure how you wish to authenticate to the API by customizing the ``DEFAULT_AUTHENTICATION_CLASSES`` key in the ``REST_FRAMEWORK`` setting (more information on this page : https://www.django-rest-framework.org/api-guide/authentication/)
+
+GET
+---
+
+Accessing the endpoint ``/api/tickets/`` with a **GET** request will return you the complete list of tickets.
+
+Accessing the endpoint ``/api/tickets/<ticket-id>`` with a **GET** request will return you the data of the ticket you provided the ID.
+
+POST
+----
+
+Accessing the endpoint ``/api/tickets/`` with a **POST** request will let you create a new tickets.
+
+You need to provide a JSON body with the following data :
+
+- **queue**: ID of the queue
+- **title**: the title (subject) of the ticket
+- **description**: the description of the ticket
+- **resolution**: an optonal text for the resoltuion of the ticket
+- **submitter_email**: the email of the ticket submitter
+- **assigned_to**: ID of the ticket's assigned user
+- **status**: integer corresponding to the status (OPEN=1, REOPENED=2, RESOLVED=3, CLOSED=4, DUPLICATE=5). It is OPEN by default.
+- **on_hold**: boolean to indicates if the ticket is on hold
+- **priority**: integer corresponding to different degrees of priority 1 to 5 (1 is Critical and 5 is Very Low)
+- **due_date**: date representation for when the ticket is due
+- **last_escalation**: date representation of when last escalation has been done
+- **merged_to**: ID of the ticket to which it is merged
+
+Here is an example of a cURL request to create a ticket (using Basic authentication) ::
+
+    curl --location --request POST 'http://127.0.0.1:8000/api/tickets/' \
+    --header 'Authorization: Basic YWRtaW46YWRtaW4=' \
+    --header 'Content-Type: application/json' \
+    --data-raw '{"queue": 1, "title": "Test Ticket API", "description": "Test create ticket from API", "submitter_email": "test@mail.com","priority": 4}'
+
+PUT
+---
+
+Accessing the endpoint ``/api/tickets/<ticket-id>`` with a **PUT** request will let you update the data of the ticket you provided the ID.
+
+You must include all fields in the JSON body.
+
+PATCH
+-----
+
+Accessing the endpoint ``/api/tickets/<ticket-id>`` with a **PATCH** request will let you do a partial update of the data of the ticket you provided the ID.
+
+You can include only the fields you need to update in the JSON body.
+
+DELETE
+------
+
+Accessing the endpoint ``/api/tickets/<ticket-id>`` with a **DELETE** request will let you delete the ticket you provided the ID.

docs/index.rst

@@ -16,9 +16,9 @@ Contents
    settings
    spam
    custom_fields
+   api
    integration
    teams
-   contributing
    license
 
 
@@ -40,6 +40,7 @@ django-helpdesk has been designed for small businesses who need to receive, mana
 * Tickets can be opened via email
 * Multiple queues / categories of tickets
 * Integrated FAQ / knowledgebase
+* API to manage tickets
 
 Customer-facing Capabilities
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -62,6 +63,8 @@ If a user is a staff member, they get general helpdesk access, including:
 5. Follow up or respond to tickets
 6. Assign tickets to themselves or other staff members
 7. Resolve tickets
+8. Merge multiple tickets into one
+9. Create, Read, Update and Delete tickets through a REST API
 
 Optionally, their access to view tickets, both on the dashboard and through searches and reports, may be restricted by a list of queues to which they have been granted membership. Create and update permissions for individual tickets are not limited by this optional restriction.
 

docs/install.rst

@@ -27,10 +27,10 @@ Installing using PIP
 
 Try using ``pip install django-helpdesk``. Go and have a beer to celebrate Python packaging.
 
-Checkout ``master`` from git (Cutting Edge)
+Checkout ``stable`` from git (Cutting Edge)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you're planning on editing the code or just want to get whatever is the latest and greatest, you can clone the official Git repository with ``git clone git://github.com/django-helpdesk/django-helpdesk.git``. We use the ``master`` branch as our development branch for the next major release of ``django-helpdesk``.
+If you're planning on editing the code or just want to get whatever is the latest and greatest, you can clone the official Git repository with ``git clone git://github.com/django-helpdesk/django-helpdesk.git``. We use the ``stable`` branch as our development branch for the next major release of ``django-helpdesk``.
 
 Copy the ``helpdesk`` folder into your ``PYTHONPATH``.
 
@@ -59,13 +59,14 @@ errors with trying to create User settings.
         'django.contrib.humanize',  # Required for elapsed time formatting
         'bootstrap4form', # Required for nicer formatting of forms with the default templates
         'account',  # Required by pinax-teams
-        'pinax.invitations',  # required by pinax-teams
-        'pinax.teams',  # team support
-        'reversion',  # required by pinax-teams
+        'pinax.invitations',  # Required by pinax-teams
+        'pinax.teams',  # Team support
+        'reversion',  # Required by pinax-teams
+        'rest_framework',  # required for the API
         'helpdesk',  # This is us!
     )
 
-   Note: you do not need to use pinax-teams. To dissable teams see the :doc:`teams` section.
+   Note: you do not need to use pinax-teams. To disable teams see the :doc:`teams` section.
 
    Your ``settings.py`` file should also define a ``SITE_ID`` that allows multiple projects to share
    a single database, and is required by ``django.contrib.sites`` in Django 1.9+.
@@ -75,11 +76,11 @@ errors with trying to create User settings.
 
 2. Make sure django-helpdesk is accessible via ``urls.py``. Add the following line to ``urls.py``::
 
-     url(r'helpdesk/', include('helpdesk.urls')),
+     path('helpdesk/', include('helpdesk.urls')),
 
    Note that you can change 'helpdesk/' to anything you like, such as 'support/' or 'help/'. If you want django-helpdesk to be available at the root of your site (for example at http://support.mysite.tld/) then the line will be as follows::
 
-     url(r'', include('helpdesk.urls', namespace='helpdesk')),
+     path('', include('helpdesk.urls', namespace='helpdesk')),
 
    This line will have to come *after* any other lines in your urls.py such as those used by the Django admin.
 
@@ -90,7 +91,7 @@ errors with trying to create User settings.
 
    Migrate using Django migrations::
 
-     ./manage.py migrate helpdesk
+     python manage.py migrate helpdesk
 
 4. Include your static files in your public web path::