From 99a13d1f219bb423689e7d8ae8f4d7647c754283 Mon Sep 17 00:00:00 2001
From: Konstantin Togoi <konstantin.togoi@gmail.com>
Date: Mon, 13 Apr 2020 15:29:00 +0300
Subject: [PATCH] add examples of signatures

---
 docs/source/session.rst | 111 ++++++++++++++++++++++++++++++----------
 1 file changed, 85 insertions(+), 26 deletions(-)

diff --git a/docs/source/session.rst b/docs/source/session.rst
index 2e09cba..a0220f0 100644
--- a/docs/source/session.rst
+++ b/docs/source/session.rst
@@ -1,44 +1,61 @@
 Session
 =======
 
+The session makes **GET** requests when you call instance of :code:`APIMethod`
+class that are returned as attributes of an :code:`API` class instance.
+
 Request
 -------
 
-The session makes **GET** requests when you call methods of an :code:`API` instance.
-Lets consider example at https://api.mail.ru/docs/guides/restapi/#client:
+By default, the session
+(:code:`CodeSession`, :code:`ImplicitSession`, :code:`PasswordSession`, :code:`RefreshSession`)
+tries to infer which signature generation circuit to use:
+
+* if :code:`uid` and :code:`private_key` are not empty strings - **client-server** signature generation circuit is used
+* else if :code:`secret_key` is not an empty string - **server-server** signature generation circuit is used
+* else exception is raised
+
+You can explicitly set a signature generation circuit for signing requests
+by passing to :code:`API` one of the sessions below.
+
+Client-Server signature generation circuit
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's consider the following example of API request with client-server signature:
 
 .. code-block:: python
 
     from aiomailru import TokenSession, API
 
-    app_id = 123456
-    private_key = '7815696ecbf1c96e6894b779456d330e'
-    secret_key = ''
-    session_key = 'be6ef89965d58e56dec21acb9b62bdaa'
-    uid = '1324730981306483817'
-
-    session = TokenSession(app_id, private_key, secret_key, access_token, uid)
+    session = TokenSession(
+        app_id=423004,
+        private_key='7815696ecbf1c96e6894b779456d330e',
+        secret_key='',
+        access_token='be6ef89965d58e56dec21acb9b62bdaa',
+        uid='1324730981306483817',
+    )
     api = API(session)
 
-    events = await api.stream.get()
+    friends = await api.friends.get()
 
-It is equivalent to the following **GET** request:
+It is equivalent to **GET** request:
 
 .. code-block:: shell
 
-    https://appsmail.ru/platform/api?method=stream.get&app_id=123456&session_key=be6ef89965d58e56dec21acb9b62bdaa&sig=5073f15c6d5b6ab2fde23ac43332b002
-
-By default, the session tries to infer which signature circuit to use:
+    https://appsmail.ru/platform/api
+        ?method=friends.get
+        &app_id=423004
+        &session_key=be6ef89965d58e56dec21acb9b62bdaa
+        &sig=5073f15c6d5b6ab2fde23ac43332b002
 
-* if :code:`uid` and :code:`private_key` are not empty strings - **client-server** signature circuit is used https://api.mail.ru/docs/guides/restapi/#client
-* else if :code:`secret_key` is not an empty string - **server-server** signature circuit is used https://api.mail.ru/docs/guides/restapi/#server
-* else exception is raised
+The following steps were taken:
 
-You can explicitly choose a circuit for signing requests by passing
-to :code:`API` one of the following sessions:
+1. request parameters were sorted and concatenated - :code:`app_id=423004method=friends.getsession_key=be6ef89965d58e56dec21acb9b62bdaa`
+2. :code:`uid`, sorted request parameters, :code:`private_key` were concatenated - :code:`1324730981306483817app_id=423004method=friends.getsession_key=be6ef89965d58e56dec21acb9b62bdaa7815696ecbf1c96e6894b779456d330e`
+3. signature :code:`5073f15c6d5b6ab2fde23ac43332b002` calculated as MD5 of the previous string
+4. signature appended to **GET** request parameters
 
-Client-Server signature circuit
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For more details, see https://api.mail.ru/docs/guides/restapi/#client.
 
 ClientSession
 ^^^^^^^^^^^^^
@@ -105,8 +122,45 @@ RefreshClientSession
         api = API(session)
         ...
 
-Server-Server signature circuit
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Server-Server signature generation circuit
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's consider the following example of API request with server-server signature:
+
+.. code-block:: python
+
+    from aiomailru import TokenSession, API
+
+    session = TokenSession(
+        app_id=423004,
+        private_key='',
+        secret_key='3dad9cbf9baaa0360c0f2ba372d25716',
+        access_token='be6ef89965d58e56dec21acb9b62bdaa',
+        uid='',
+    )
+    api = API(session)
+
+    friends = await api.friends.get()
+
+It is equivalent to **GET** request:
+
+.. code-block:: shell
+
+    https://appsmail.ru/platform/api
+        ?method=friends.get
+        &app_id=423004
+        &session_key=be6ef89965d58e56dec21acb9b62bdaa
+        &sig=4a05af66f80da18b308fa7e536912bae
+
+The following steps were taken:
+
+1. parameter :code:`secure` = :code:`1` appended to parameters
+2. request parameters were sorted and concatenated - :code:`app_id=423004method=friends.getsecure=1session_key=be6ef89965d58e56dec21acb9b62bdaa`
+3. sorted request parameters and :code:`secret_key` were concatenated - :code:`1324730981306483817app_id=423004method=friends.getsession_key=be6ef89965d58e56dec21acb9b62bdaa3dad9cbf9baaa0360c0f2ba372d25716`
+4. signature :code:`4a05af66f80da18b308fa7e536912bae` calculated as MD5 of the previous string
+5. signature appended to **GET** request parameters
+
+For more details, see  https://api.mail.ru/docs/guides/restapi/#server.
 
 ServerSession
 ^^^^^^^^^^^^^
@@ -177,7 +231,7 @@ Response
 --------
 
 By default, a session after executing request returns response's body
-as :code:`dict` if executing was successful, otherwise it raises an exception.
+as :code:`dict` if executing was successful, otherwise it raises exception.
 
 You can pass :code:`pass_error` parameter to :code:`TokenSession`
 for returning original response (including errors).
@@ -185,10 +239,15 @@ for returning original response (including errors).
 Error
 -----
 
-In case of an error, by default, an exception is raised.
+In case of an error, by default, exception is raised.
 You can pass :code:`pass_error` parameter to :code:`TokenSession`
 for returning original error's body as :code:`dict`:
 
 .. code-block:: python
 
-    {"error": {"error_code": 202, "error_msg": "Access to this object is denied"}}
+    {
+        "error": {
+            "error_code": 202,
+            "error_msg": "Access to this object is denied"
+        }
+    }