Added additional information for identity API

1 files changed, 101 insertions, 54 deletions

diff --git a/source/identity.rst b/source/identity.rst
index dd68fae..11b2d29 100644
--- a/source/identity.rst
+++ b/source/identity.rst
@@ -1,14 +1,64 @@
 GNUnet Identity API Service
 ===========================
 
+Definition
+==========
+
 Variables in single quotes ``'...'`` can or must be changed according to your specific case.
 
 ``public_key`` is the public key of an identity.
 
-``name`` is the name of an identity. ``newname`` is the new name of an identity.
+``name`` is the name of an identity. 
+
+``newname`` is the new name of an identity for the rename request.
+
+``subsystem`` is a subsystem, e.g. namestore.
+
+Identity
+--------
+
+An identity consists of a ``public key`` and a ``name``. An identity can be assigned to a ``subsystem``. Each subsystem can only have one default identity.
+
+
+Error Response
+--------------
+
+An error response is sent in the JSON format: ``{"error":"*error_description*"}``
+
+Numbers are added for references inside the documentation only.
 
-``subsystem`` is a subsystem of GNUnet.
+Error descriptions are::
+    
+    Nr. Error Description           - Explanation
+    1)  Unknown Error               - Error is not specified
+    2)  No identity found           - Identity was not found with given name, public key or no identity was found at all
+    3)  Missing identity public key - Identity public key length is zero
+    4)  Missing identity name       - Identity name length is zero
+    5)  Missing subsystem name      - Subsystem name length is zero
+    6)  No data                     - No JSON data given
+    7)  Data invalid                - Wrong JSON data given
+    8)  Rename failed               - Rename request failed due to wrong name, etc.
+    9)  Setting subsystem failed    - Setting the subsystem for an identity failed (usually this error does not occur)
 
+Error ``1)`` is always possible and is not listed in following requests.
+
+ATTENTION: Any error message from the Identity API (not REST API) can occur and can be returned in the error response. These responses are not listed here.
+
+Response Code
+-------------
+
+A response of a message has a HTTP response code. Usually, this code is 200 OK for a successful response. The code changes in some cases::
+
+    a) 200 OK         - Normal response (but may contain an error message)
+    b) 201 Created    - Success after POST request
+    c) 204 No Content - Success PUT or DELETE request
+    d) 404 Not Found  - Identity is not found with identifier
+    e) 409 Conflict   - PUT or POST request not possible due to existing duplicate
+    
+``d) 404 Not Found`` is always used when the error message is either ``2)``, ``3)`` or ``4)``.
+
+Requests
+========
 
 GET Requests
 ------------
@@ -26,7 +76,7 @@ GET Requests
 +--------------------+---------------------------------------------------------------+
 |**Success Response**|[{"pubkey":"*public_key*", "name":"*name*"},...]               |
 +--------------------+---------------------------------------------------------------+
-|**Error Response**  |{"error":"*error_desc*"}                                       |
+|**Error Response**  | ``2) No identity found``                                      |
 +--------------------+---------------------------------------------------------------+
 |**Attention**       | The response in this request is an array!                     |
 +--------------------+---------------------------------------------------------------+
@@ -46,7 +96,8 @@ GET Requests
 +--------------------+----------------------------------------------------------------+
 |**Success Response**|{"pubkey":"*public_key*", "name":"*name*"}                      |
 +--------------------+----------------------------------------------------------------+
-|**Error Response**  |{"error":"*error_desc*"}                                        |
+|**Error Response**  | | ``2) No identity found``; ``3) Missing identity public key`` |
+|                    | | or ``4) Missing identity name``                              |
 +--------------------+----------------------------------------------------------------+
 
 |
@@ -64,30 +115,29 @@ GET Requests
 +--------------------+---------------------------------------------------------------+
 |**Success Response**|{"pubkey":"*public_key*", "name":"*name*"}                     |
 +--------------------+---------------------------------------------------------------+
-|**Error Response**  |{"error":"*error_desc*"}                                       |
+|**Error Response**  | ``2) No identity found``; ``5) Missing subsystem name``       |
 +--------------------+---------------------------------------------------------------+
 
-
 POST Request
 ------------
 
-+--------------------+----------------------------------------------------+
-|**Title**           |Creates an identity                                 |
-+--------------------+----------------------------------------------------+
-|**URL**             |:literal:`/identity`                                |
-+--------------------+----------------------------------------------------+
-|**Method**          |**POST**                                            |
-+--------------------+----------------------------------------------------+
-|**URL Params**      |none                                                |
-+--------------------+----------------------------------------------------+
-|**Data Params**     | {"name":'*name*'}                                  |
-+--------------------+----------------------------------------------------+
-|**Success Response**|Response Code: :literal:`201` (Created)             |
-+--------------------+----------------------------------------------------+
-|**Error Response**  | | {"error":"*error_desc*"}                         |
-|                    | | *or*                                             |
-|                    | | Response Code: :literal:`409` (Conflict)         |
-+--------------------+----------------------------------------------------+
++--------------------+---------------------------------------------------------------+
+|**Title**           |Creates an identity                                            |
++--------------------+---------------------------------------------------------------+
+|**URL**             |:literal:`/identity`                                           |
++--------------------+---------------------------------------------------------------+
+|**Method**          |**POST**                                                       |
++--------------------+---------------------------------------------------------------+
+|**URL Params**      |none                                                           |
++--------------------+---------------------------------------------------------------+
+|**Data Params**     | {"name":'*name*'}                                             |
++--------------------+---------------------------------------------------------------+
+|**Success Response**| Response Code: :literal:` b) 201 Created`                     |
++--------------------+---------------------------------------------------------------+
+|**Error Response**  | | ``6) No data``; ``7) Data invalid``                         |
+|                    | | *or*                                                        |
+|                    | | Response Code: ``e) 409 Conflict`` if name in use           |
++--------------------+---------------------------------------------------------------+
 
 PUT Request
 -----------
@@ -103,13 +153,13 @@ PUT Request
 +--------------------+----------------------------------------------------------------+
 |**Data Params**     | {"newname":'*newname*'}                                        |
 +--------------------+----------------------------------------------------------------+
-|**Success Response**|Response Code: :literal:`204` (No Content)                      |
+|**Success Response**| Response Code: :literal:`c) 204 No Content`                    |
 +--------------------+----------------------------------------------------------------+
-|**Error Response**  | | {"error":"*error_desc*"}                                     |
+|**Error Response**  | | ``2) No identity found``; ``3) Missing identity public key`` |
+|                    | | or ``4) Missing identity name``; ``6) No data``;             |
+|                    | | ``7) Data invalid``; ``8) Rename failed``                    |
 |                    | | *or*                                                         |
-|                    | | Response Code: :literal:`404` (Not Found)                    |
-|                    | | *or*                                                         |
-|                    | | Response Code: :literal:`409` (Conflict)                     |
+|                    | | Response Code: :literal:`e) 409 Conflict` if newname in use  |
 +--------------------+----------------------------------------------------------------+
 
 |
@@ -117,7 +167,7 @@ PUT Request
 +--------------------+----------------------------------------------------------------+
 |**Title**           |Sets identity as default for a subsystem                        |
 +--------------------+----------------------------------------------------------------+
-|**URL**             | ``/identity/pubkey/'public_key'`` or ``/identity/name/'name'`` |
+|**URL**             | ``/identity/subsystem/'name'``                                 |
 +--------------------+----------------------------------------------------------------+
 |**Method**          |**PUT**                                                         |
 +--------------------+----------------------------------------------------------------+
@@ -125,13 +175,11 @@ PUT Request
 +--------------------+----------------------------------------------------------------+
 |**Data Params**     | {"subsystem":'*subsystem*'}                                    |
 +--------------------+----------------------------------------------------------------+
-|**Success Response**|Response Code: :literal:`204` (No Content)                      |
+|**Success Response**| Response Code: :literal:`c) 204 No Content`                    |
 +--------------------+----------------------------------------------------------------+
-|**Error Response**  | | {"error":"*error_desc*"}                                     |
-|                    | | *or*                                                         |
-|                    | | Response Code: :literal:`404` (Not Found)                    |
-|                    | | *or*                                                         |
-|                    | | Response Code: :literal:`409` (Conflict)                     |
+|**Error Response**  | | ``2) No identity found``; ``4) Missing identity name``;      |
+|                    | | ``6) No data``; ``7) Data invalid``;                         |
+|                    | | ``9)  Setting subsystem failed``                             |
 +--------------------+----------------------------------------------------------------+
 
 DELETE Request
@@ -148,28 +196,27 @@ DELETE Request
 +--------------------+----------------------------------------------------------------+
 |**Data Params**     |none                                                            |
 +--------------------+----------------------------------------------------------------+
-|**Success Response**|Response Code: :literal:`204` (No Content)                      |
+|**Success Response**| Response Code: :literal:`c) 204 No Content`                    |
 +--------------------+----------------------------------------------------------------+
-|**Error Response**  | | {"error":"*error_desc*"}                                     |
-|                    | | *or*                                                         |
-|                    | | Response Code: :literal:`404` (Not Found)                    |
+|**Error Response**  | | ``2) No identity found``; ``3) Missing identity public key`` |
+|                    | | or ``4) Missing identity name``                              |
 +--------------------+----------------------------------------------------------------+
 
 OPTIONS Request
 ---------------
 
-+--------------------+---------------------------------------------------------+
-|**Title**           |Gets request options                                     |
-+--------------------+---------------------------------------------------------+
-|**URL**             |:literal:`/identity`                                     |
-+--------------------+---------------------------------------------------------+
-|**Method**          |**OPTIONS**                                              |
-+--------------------+---------------------------------------------------------+
-|**URL Params**      |none                                                     |
-+--------------------+---------------------------------------------------------+
-|**Data Params**     |none                                                     |
-+--------------------+---------------------------------------------------------+
-|**Success Response**|                                                         |
-+--------------------+---------------------------------------------------------+
-|**Error Response**  |none                                                     |
-+--------------------+---------------------------------------------------------+
++--------------------+----------------------------------------------------------------+
+|**Title**           |Gets request options                                            |
++--------------------+----------------------------------------------------------------+
+|**URL**             |:literal:`/identity`                                            |
++--------------------+----------------------------------------------------------------+
+|**Method**          |**OPTIONS**                                                     |
++--------------------+----------------------------------------------------------------+
+|**URL Params**      |none                                                            |
++--------------------+----------------------------------------------------------------+
+|**Data Params**     |none                                                            |
++--------------------+----------------------------------------------------------------+
+|**Success Response**|                                                                |
++--------------------+----------------------------------------------------------------+
+|**Error Response**  |none                                                            |
++--------------------+----------------------------------------------------------------+