Namestore API Service
=====================

Definition
~~~~~~~~~~

Variables in single quotes ``'...'`` can or must be changed according to your specific case.

``name`` is the name of a zone. A zone is the name of an identity in this case.

.. _ref-gnsrecord:

GNS Record
----------

Namestore entries are GNS records. GNS records have a ``record_type``, a ``value``, an ``expiration_time``, a ``flag`` and a ``record_name``.
Adding a GNS records with the same record_name overwrites the old GNS record.

A GNS record is sent in the JSON format: ``{"value": "value", "record_type": "type", "expiration_time": "time", "flag": flag, "record_name": "rname"}``

``type`` is the type of the record, e.g. "PKEY" for private key. It can be ANY, PKEY, NICK, LEHO, VPN, GNS2DNS, BOX, PLACE, PHONE, ID_ATTR, ID_TOKEN, ID_TOKEN_METADATA, CREDENTIAL, POLICY, ATTRIBUTE, ABE_KEY, ABE_MASTER. You can find more information in header ``src/gnunet_gnsrecord_lib.h``

``value`` is the value of the specific type of the record, e.g. the private key of an identity.

``time`` is the expiration time of the record either "never" or fancy time (see GNUNET_STRINGS_fancy_time_to_absolute)

``flag`` is the option of the record. Either 0 for none, 2 for private, 8 for relative expiration or 16 if all other records have expired. ``flag`` must be a number.

``rname`` is the name of the record.

Error Response
--------------

An error response is sent in the JSON format: ``{"error":"*error_description*"}``

Following numbers are added for references inside the documentation only.

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, this is combined with the HTTP Error Code 404 Not Found
    3)  No default zone specified   - Identity name was not given and no identiy was added to the subsystem namestore 
    4)  Namestore action failed     - The task of the namestore API (not REST API) failed
    5)  No data                     - Missing data
    6)  Data invalid                - Wrong data given
    7)  Error storing records       - POST request failed
    8)  Deleting record failed      - DELETE request failed
    9)  No record found             - Delete failed due to missing record, this is combined with the HTTP Error Code 404 Not Found

Error ``1)`` is always possible and is not listed in following requests.

ATTENTION: Any error message from the Namestore API (not REST API) can occur and can be returned in the error response. These responses are not listed here.

Requests
~~~~~~~~

GET Request
------------

+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Title**           |Returns all namestore entries of default identity                                                                          |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**URL**             |:literal:`/namestore`                                                                                                      |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Method**          |**GET**                                                                                                                    |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**URL Params**      |none                                                                                                                       |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Data Params**     |none                                                                                                                       |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Success Response**|[{"value": "*value*", "record_type": "*type*", "expiration_time": "*time*", "flag": *flag*, "record_name": "*rname*"},...] |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Error Response**  | {"error":"*error_desc*"} :sup:`3; 4`                                                                                      |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+

|

+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Title**           |Returns all namestore entries for one zone specified by its name                                                           |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**URL**             |:literal:`/namestore/'name'`                                                                                               |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Method**          |**GET**                                                                                                                    |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**URL Params**      |none                                                                                                                       |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Data Params**     |none                                                                                                                       |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Success Response**|[{"value": "*value*", "record_type": "*type*", "expiration_time": "*time*", "flag": *flag*, "record_name": "*rname*"},...] |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Error Response**  | {"error":"*error_desc*"} :sup:`2; 4`                                                                                      |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+

POST Request
------------

+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Title**           |Creates a namestore entry for default identity                                                                             |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**URL**             |:literal:`/namestore`                                                                                                      |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Method**          |**POST**                                                                                                                   |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**URL Params**      |none                                                                                                                       |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Data Params**     |{"value": "*value*", "record_type": "*type*", "expiration_time": "*time*", "flag": *flag*, "record_name": "*rname*"}       |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Success Response**|Response Code: :literal:`204` (No Content)                                                                                 |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Error Response**  | {"error":"*error_desc*"} :sup:`3; 4; 5; 6; 7`                                                                             |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+

|

+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Title**           |Creates a namestore entry for one zone specified by its name                                                               |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**URL**             |:literal:`/namestore/'name'`                                                                                               |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Method**          |**POST**                                                                                                                   |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**URL Params**      |none                                                                                                                       |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Data Params**     |{"value": "*value*", "record_type": "*type*", "expiration_time": "*time*", "flag": *flag*, "record_name": "*rname*"}       |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Success Response**|Response Code: :literal:`204` (No Content)                                                                                 |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Error Response**  | {"error":"*error_desc*"} :sup:`2; 4; 5; 6; 7`                                                                             |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+


DELETE Request
--------------

+--------------------+---------------------------------------------------------------------------------------------------------------------------+
| **Title**          | Deletes specific namestore entry for default identity                                                                     |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**URL**             |:literal:`/namestore?record_name='rname'`                                                                                  |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Method**          | **DELETE**                                                                                                                |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**URL Params**      | none                                                                                                                      |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Data Params**     | none                                                                                                                      |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Success Response**| Response Code: :literal:`204` (No Content)                                                                                |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Error Response**  | {"error":"*error_desc*"} :sup:`3; 4; 6; 8; 9`                                                                             |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+

|

+--------------------+---------------------------------------------------------------------------------------------------------------------------+
| **Title**          | Deletes specific namestore entry in specific zone                                                                         |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**URL**             |:literal:`/namestore/'name'?record_name='rname'`                                                                           |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Method**          | **DELETE**                                                                                                                |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**URL Params**      | none                                                                                                                      |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Data Params**     | none                                                                                                                      |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Success Response**| Response Code: :literal:`204` (No Content)                                                                                |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Error Response**  | {"error":"*error_desc*"} :sup:`2; 4; 6; 8; 9`                                                                             |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+


OPTIONS Request
---------------

+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Title**           |Gets request options                                                                                                       |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**URL**             |:literal:`/namestore`                                                                                                      |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Method**          |**OPTIONS**                                                                                                                |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**URL Params**      |none                                                                                                                       |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Data Params**     |none                                                                                                                       |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Success Response**|                                                                                                                           |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
|**Error Response**  |none                                                                                                                       |
+--------------------+---------------------------------------------------------------------------------------------------------------------------+
