..
   SPDX-License-Identifier: CC-BY-SA 4.0

   Copyright (C) 2024 David Aderbauer & The Eonvelope Contributors
   Licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.

API Instructions
================

If you run a Eonvelope server or have access to one, the easiest way
to get started with the API is via the redoc and swagger interfaces.

These can be found under */api/schema/redoc* and */api/schema/swagger*.
The redoc interface for the user management API can be found under */api/auth/openapi.html*.

Alternatively you can also get a raw yaml OpenAPI schema from */api/schema*.
The raw user management API schema is available under */api/auth/openapi.yaml* or */api/auth/openapi.json*.

.. note::
    These interfaces are not available in slim mode.

If you have no option to run Eonvelope, you can refer to :ref:`the API-schema section <API Schema>` for the same schema files.
You can render it to any API overview using one of the existing webtools or the docker image provided by swagger

.. code-block:: bash

    docker run -p 8080:8080 -e SWAGGER_JSON=/schema.yml -v /path/to/schema.yml:/schema.yml swaggerapi/swagger-ui

In general the URLs of the API endpoints are designed in parallel to
the webapps URLs with a prefix */api/v1/*.

.. note::
    All endpoints for interactions with the data and for authentication via api do not end in a slash.

To get an idea of what the different endpoints do try using the webapp
or reading :doc:`its manual <web-instructions>` first.

In addition to the features of the webapp the API offers vastly extended options for filtering.
It also always you to download hand-picked email, attachment and correspondent files in batches as compact mailbox formats.

.. note::
    If you dont proxy Eonvelope and want to request the API, you will have to ignore the self-signed certificate warnings.
    Using cURL you can do so via the `-k` option.


API Schema
----------

.. toctree::
    :maxdepth: 1

    api-schema

The API version of the django-allauth user management is not documented in this schema.
Please refer to `its own OpenAPI schema <https://django-allauth.readthedocs.io/en/latest/headless/openapi-specification/>`_ for full information.
Replace ``_allauth`` in their URLs with ``api/auth`` to map it to the Eonvelope endpoints.


Authentication
--------------

To authenticate via the API you have 4 options:

- Basic auth: Authenticate directly at every endpoint with your credentials.
    This option is only available if you don't have multi-factor-authentication turned on.

    .. code-block:: bash

        curl -kX 'GET' -u user:password https://eonvelope.mydomain.tld/api/v1/emails/1

- Token authentication: Authenticate via an API token.
    You can get a persistent one from the admin panel. This method is recommended for use in scripts and manual use.

    .. code-block:: bash

        curl -kX 'GET' -H 'Authorization: Token your_key' https://eonvelope.mydomain.tld/api/v1/emails/1

- Session authentication: Authenticate using a session cookie.
    This always requires that you add a recent CSRF token to the request. You can find one in the cookies of the web-interface.

    .. code-block:: bash

        curl -kX 'GET' -b 'sessionid=your_session_cookie; csrftoken=your_csrf_token' -H 'X-CSRFTOKEN: your_csrf_token' https://eonvelope.mydomain.tld/api/v1/emails/1

- Session Token Authentication: Authenticate using a session token.
    This option is implemented by the API of headless django-allauth and is mostly intended for use by alternative frontends.

    .. code-block:: bash

        curl -kX 'POST' -d '{"username": "myname", "password": "mypwd"}' https://eonvelope.mydomain.tld/api/auth/app/v1/auth/login

    This will return a session token in the meta section of the json response.
    Note the missing / at the end of the login URL.

    .. code-block:: bash

        curl -kX 'GET' -H 'X-Session-Token: your_token' https://eonvelope.mydomain.tld/api/v1/emails/1


For more details see `the django restframework documentation on the matter <https://www.django-rest-framework.org/api-guide/authentication/#sessionauthentication>`_.

Gotcha Notes
------------

There may be a few unexpected quirks in the api, especially when it comes to field naming.
These are listed here.

Version 1
:::::::::

The mail_address field returned by account endpoints refers to the username field from the web interface.
It does NOT need to contain a valid mail_address.
The outward facing name in the web interface was changed to 'username' for semantic compatibility with JMAP.