[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] [gnunet-rest-api] 06/07: Added additional information for i
|
From: |
gnunet |
|
Subject: |
[GNUnet-SVN] [gnunet-rest-api] 06/07: Added additional information for identity API |
|
Date: |
Sun, 12 Aug 2018 23:08:38 +0200 |
This is an automated email from the git hooks/post-receive script.
phil pushed a commit to branch master
in repository gnunet-rest-api.
commit c89eef6cc42b6d7bfcfd761f1c9f7cf260c006e7
Author: Phil <address@hidden>
AuthorDate: Sun Aug 12 01:40:14 2018 +0200
Added additional information for identity API
---
source/identity.rst | 155 ++++++++++++++++++++++++++++++++++------------------
1 file 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
|
++--------------------+----------------------------------------------------------------+
--
To stop receiving notification emails like this one, please contact
address@hidden
- [GNUnet-SVN] [gnunet-rest-api] branch master updated (5e5750f -> c4883a8), gnunet, 2018/08/12
- [GNUnet-SVN] [gnunet-rest-api] 01/07: added identity get, gnunet, 2018/08/12
- [GNUnet-SVN] [gnunet-rest-api] 02/07: -wip documentation, gnunet, 2018/08/12
- [GNUnet-SVN] [gnunet-rest-api] 06/07: Added additional information for identity API,
gnunet <=
- [GNUnet-SVN] [gnunet-rest-api] 03/07: add namestore, gnunet, 2018/08/12
- [GNUnet-SVN] [gnunet-rest-api] 04/07: Changed identity, gns and namestore, gnunet, 2018/08/12
- [GNUnet-SVN] [gnunet-rest-api] 05/07: Changed identity, wip namestore, gnunet, 2018/08/12
- [GNUnet-SVN] [gnunet-rest-api] 07/07: fix apis, gnunet, 2018/08/12