From b8451eef164bcab0598de456b8fc4c5e70687653 Mon Sep 17 00:00:00 2001 From: Benbb96 Date: Thu, 7 Apr 2022 00:43:00 +0200 Subject: [PATCH] Add an API section in documentation + fix small things --- docs/api.rst | 59 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 5 +++- docs/install.rst | 19 ++++++++-------- 3 files changed, 73 insertions(+), 10 deletions(-) create mode 100644 docs/api.rst diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 00000000..c11df0c5 --- /dev/null +++ b/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/`` 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/`` 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/`` 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/`` with a **DELETE** request will let you delete the ticket you provided the ID. diff --git a/docs/index.rst b/docs/index.rst index 15888094..6ed44704 100644 --- a/docs/index.rst +++ b/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. diff --git a/docs/install.rst b/docs/install.rst index e1107b07..6b34c3d4 100644 --- a/docs/install.rst +++ b/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::