Registration
============

API Views
---------

There are two views used in the registration workflow:

.. _register-view:

register
~~~~~~~~

.. autofunction:: rest_registration.api.views.register

.. _verify-registration-view:

verify-registration
~~~~~~~~~~~~~~~~~~~

.. autofunction:: rest_registration.api.views.verify_registration

Assuming that the Django REST registration views are served at
``https://backend-host/api/v1/accounts/``
then the ``register``, ``verify_registration`` views are served as:

*   ``https://backend-host/api/v1/accounts/register/``
*   ``https://backend-host/api/v1/accounts/verify-registration/``

accordingly.

.. _register-verification-workflow:

Verification workflow
---------------------

Let's describe it by example.
We're assuming that:

-   the Django REST Registration views are served at
    ``https://backend-host/api/v1/accounts/``
-   you have :ref:`register-verification-enabled-setting` set to ``True``
    (this by default)
-   you configured :ref:`register-verification-url-setting` to be
    ``https://frontend-host/verify-user/``

Then the verification workflow looks as follows:

1.  The user who wants to register itself sends AJAX POST request to
    ``https://backend-host/api/v1/accounts/register/`` endpoint.
    Usually this happens via front-end aplication, which could be hosted
    on ``https://frontend-host/``.

2.  Assuming the registration was correct, The ``register`` endpoint
    will generate an e-mail which will contain an URL which the
    newly registered user should click to activate his/her account.
    the URL would be in a form:

    ``https://frontend-host/verify-user/?user_id=<user id>&timestamp=<timestamp>&signature=<signature>``

    (You can change the way the URL is generated by overriding
    :ref:`verification-url-builder-setting`)

3.  The frontend endpoint (which is not provided by Django REST Registration)
    ``https://frontend-host/verify-user/`` would receive following GET
    parameters:

    - ``user_id``
    - ``timestamp``
    - ``signature``

    and then it should perform AJAX request to
    ``https://backend-host/api/v1/accounts/verify-registration/``
    via HTTP POST with following JSON payload:

    .. code:: javascript

        {
            "user_id": "<user id>",
            "timestamp": "<timestamp>",
            "signature": "<signature>"
        }

    and then show a message to the user depending on the response from
    backend server.

Default serializers
-------------------

.. _default-register-user-serializer:

DefaultRegisterUserSerializer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: rest_registration.api.serializers.DefaultRegisterUserSerializer

Signals
-------

.. _register-signals:

There are many cases where only a small bit of additional logic needs to 
be injected into the registration process, and writing a custom workflow 
to support this represents an unnecessary amount of work. 
A more lightweight customization option is provided through two custom signals 
which the built-in registration workflows send, and custom workflows 
are encouraged to send, at specific points during the registration process; 
functions listening for these signals can then add whatever logic is needed.

For general documentation on signals and the Django dispatcher, 
consult `Django's signals documentation
<http://docs.djangoproject.com/en/stable/topics/signals/>`_. This documentation assumes 
that you are familiar with how signals work and the process of writing and 
connecting functions which will listen for signals.


.. data:: user_activated

   Sent when a user account is activated (not applicable to all
   workflows). Provides the following arguments:

   `sender`
        None - No class is sending this signal
   `user`
        A user-model instance representing the activated account.

   `request`
       The `Request <https://www.django-rest-framework.org/api-guide/requests/#requests>`_ in which the account was activated.

   This signal is automatically sent for you by the base
   :meth:`~django_rest_registration.api.views.register`, so unless
   you've overridden it you should not need to explicitly send it.


.. data:: user_registered

   Sent when a new user account is registered. Provides the following
   arguments:

   `sender`
        None - No class is sending this signal

   `user`
        A user-model instance representing the new account.

   `request`
       The `Request <https://www.django-rest-framework.org/api-guide/requests/#requests>`_ in which the account was registered.


List of settings
----------------

These settings can be used to configure registration workflow.
You should add them as keys (with values)
to your ``settings.REST_REGISTRATION`` dict.

.. jinja:: detailed_configuration__register
   :file: detailed_configuration/settings_fields.j2