django-helpdeskmig/docs/api.rst

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.

If you wish to use it, you have to add this line in your settings::

    HELPDESK_ACTIVATE_API_ENDPOINT = True

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 with their
followups and their attachment files.

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 optional 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
- **merged_to**: ID of the ticket to which it is merged

Note that ``status`` will automatically be set to OPEN. Also, some fields are not configurable during creation:
``resolution``, ``on_hold`` and ``merged_to``.

Moreover, if you created custom fields, you can add them into the body with the key ``custom_<custom-field-slug>``.

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}'

Note that you can attach one file as attachment but in this case, you cannot use JSON for the request content type.
Here is an example with form-data (curl default) ::

    curl --location --request POST 'http://127.0.0.1:8000/api/tickets/' \
    --header 'Authorization: Basic YWRtaW46YWRtaW4=' \
    --form 'queue="1"' \
    --form 'title="Test Ticket API with attachment"' \
    --form 'description="Test create ticket from API avec attachment"' \
    --form 'submitter_email="test@mail.com"' \
    --form 'priority="2"' \
    --form 'attachment=@"/C:/Users/benbb96/Documents/file.txt"'

----

Accessing the endpoint ``/api/followups/`` with a **POST** request will let you create a new followup on a ticket.

This time, you can attach multiple files thanks to the `attachments` field. Here is an example ::

    curl --location --request POST 'http://127.0.0.1:8000/api/followups/' \
    --header 'Authorization: Basic YWRtaW46YWRtaW4=' \
    --form 'ticket="44"' \
    --form 'title="Test ticket answer"' \
    --form 'comment="This answer contains multiple files as attachment."' \
    --form 'attachments=@"/C:/Users/benbb96/Documents/doc.pdf"' \
    --form 'attachments=@"/C:/Users/benbb96/Documents/image.png"'

----

Accessing the endpoint ``/api/users/`` with a **POST** request will let you create a new user.

You need to provide a JSON body with the following data :

- **first_name**: first name
- **last_name**: last name
- **username**: username
- **email**: user email
- **password**: user password

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.