Documentation: explaining verification workflow

[skip ci]

docs/detailed_configuration/register.rst

@@ -20,15 +20,62 @@ 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/
+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/
+* ``https://backend-host/api/v1/accounts/register/``
+* ``https://backend-host/api/v1/accounts/verify-registration/``
 
 accordingly.
 
+Verification workflow
+---------------------
+
+We're assuming that the Django REST Registration views are served at
+``https://backend-host/api/v1/accounts/``
+and you configured :ref:`register-verification-url-setting` to be
+``https://frontend-host/verify-user/``
+
+
+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
 -------------------
 

docs/detailed_configuration/register_email.rst

@@ -20,6 +20,65 @@ verify-email
 
 .. autofunction:: rest_registration.api.views.verify_email
 
+Assuming that the Django REST Registration views are served at
+``https://backend-host/api/v1/accounts/``
+then the ``register_email``, ``verify_email`` views are served as:
+
+* ``https://backend-host/api/v1/accounts/register-email/``
+* ``https://backend-host/api/v1/accounts/verify-email/``
+
+accordingly.
+
+Verification workflow
+---------------------
+
+We're assuming that the Django REST Registration views are served at
+``https://backend-host/api/v1/accounts/``
+and you configured :ref:`register-email-verification-url-setting` to be
+``https://frontend-host/verify-email/``
+
+
+1.  The user who wants to register new email (which is currently equivalent
+    to changing the e-mail) sends AJAX POST request to
+    ``https://backend-host/api/v1/accounts/register-email/`` endpoint.
+    Usually this happens via front-end aplication, which could be hosted
+    on ``https://frontend-host/``.
+
+2.  Assuming the registration was correct, The ``register_email`` endpoint
+    will generate an e-mail which will contain an URL which the
+    user should click to register new e-mail.
+    the URL would be in a form:
+
+    ``https://frontend-host/verify-email/?user_id=<user id>&email=<email>&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-email/`` would receive following GET
+    parameters:
+
+    - ``user_id``
+    - ``email``
+    - ``timestamp``
+    - ``signature``
+
+    and then it should perform AJAX request to
+    ``https://backend-host/api/v1/accounts/verify-email/``
+    via HTTP POST with following JSON payload:
+
+    .. code:: javascript
+
+        {
+            "user_id": "<user id>",
+            "email": "<email>",
+            "timestamp": "<timestamp>",
+            "signature": "<signature>"
+        }
+
+    and then show a message to the user depending on the response from
+    backend server.
+
 List of settings
 ----------------
 

docs/detailed_configuration/reset_password.rst

@@ -20,6 +20,63 @@ reset-password
 
 .. autofunction:: rest_registration.api.views.reset_password
 
+Assuming that the Django REST registration views are served at
+``https://backend-host/api/v1/accounts/``
+then the ``send_reset_password_link``, ``reset_password`` views are served as:
+
+* ``https://backend-host/api/v1/accounts/send-reset-password-link/``
+* ``https://backend-host/api/v1/accounts/reset-password/``
+
+accordingly.
+
+Verification workflow
+---------------------
+
+We're assuming that the Django REST Registration views are served at
+``https://backend-host/api/v1/accounts/``
+and you configured :ref:`reset-password-verification-url-setting` to be
+``https://frontend-host/reset-password/``
+
+
+1.  The user who wants to reset his/her password sends AJAX POST request to
+    ``https://backend-host/api/v1/accounts/send-reset-password-link/`` endpoint.
+    Usually this happens via front-end aplication, which could be hosted
+    on ``https://frontend-host/``.
+
+2.  Assuming the registration was correct, The ``send_reset_password_link``
+    endpoint will generate an e-mail which will contain an URL which the
+    user should click to enter new password.
+    the URL would be in a form:
+
+    ``https://frontend-host/reset-password/?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/reset-password/`` would receive following GET
+    parameters:
+
+    - ``user_id``
+    - ``timestamp``
+    - ``signature``
+
+    and after obtaining the new password it should perform AJAX request to
+    ``https://backend-host/api/v1/accounts/reset-password/``
+    via HTTP POST with following JSON payload:
+
+    .. code:: javascript
+
+        {
+            "password": "<new password>",
+            "user_id": "<user id>",
+            "timestamp": "<timestamp>",
+            "signature": "<signature>"
+        }
+
+    and then show a message to the user depending on the response from
+    backend server.
+
 List of settings
 ----------------
 

docs/index.rst

@@ -8,7 +8,7 @@ Welcome to Django REST Registration's documentation!
 
 User registration REST API, based on django-rest-framework.
 
-WARNING: ``django-rest-registration`` is only Python 3 compatible.
+WARNING: Django REST Registration is only Python 3 compatible.
 
 .. toctree::
    :maxdepth: 2

docs/install.rst

@@ -1,7 +1,7 @@
 Installation
 ============
 
-You can install ``django-rest-registration`` lastest version via pip:
+You can install Django REST Registration latest version via pip:
 
 ::
 

docs/quickstart.rst

@@ -81,7 +81,7 @@ e-mail. You also need also to replace ``'no-reply@example.com'`` with the
 e-mail address which will be used as the sender of the reset e-mail.
 
 The frontend urls are not provided by the library but should be provided
-by the user of the library, because ``django-rest-registration`` is
+by the user of the library, because Django REST Registration is
 frontend-agnostic. The frontend urls will receive parameters as GET
 query and should pass them to corresponding REST API views via HTTP POST
 request.