commit f8ddc08f36a9b76196c9b067ea8983672456a716 parent 5cceee031ff02fa51953dbd8f3ce5d78992a93c3 Author: Martin Schanzenbach <schanzen@gnunet.org> Date: Thu, 8 Sep 2022 23:52:22 +0200 Migrate REST API Diffstat:
| M | man_developers/index.rst | | | 2 | +- |
| A | man_developers/rest/config.rst | | | 124 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | man_developers/rest/gns.rst | | | 71 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | man_developers/rest/identity.rst | | | 216 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | man_developers/rest/index.rst | | | 80 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | man_developers/rest/namestore.rst | | | 188 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | man_developers/rest/peerinfo.rst | | | 98 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
7 files changed, 778 insertions(+), 1 deletion(-)
diff --git a/man_developers/index.rst b/man_developers/index.rst @@ -45,7 +45,7 @@ new chapters, sections or insightful comments. util/index.rst subsystems/index.rst - REST API <https://rest.gnunet.org> + rest/index.rst tutorial doxygen diff --git a/man_developers/rest/config.rst b/man_developers/rest/config.rst @@ -0,0 +1,124 @@ +Config API Service +================== + +Definition +~~~~~~~~~~ + +Variables in single quotes ``'...'`` can or must be changed according to your specific case. + +``config`` refers to the configuration file. + +``'section'`` is a section of settings in the configuration file. + +``'option'`` is an setting in the configuration file with a modifiable ``'value'``. + +Configuration +------------- + +The configuration file is divided in ``sections``, each consisting of various ``options`` with their corresponding ``values``. + +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) Unable to parse JSON Object from "*URI*" - Corrupt JSON data given + +Error ``1)`` is always possible and is not listed in following requests. + +ATTENTION: Any error message from the Configuration 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) 400 Bad Request - Invalid request + +Requests +~~~~~~~~ + +GET Requests +------------ + ++--------------------+---------------------------------------------------------------+ +|**Title** | Returns the config or the specified section of the config | ++--------------------+---------------------------------------------------------------+ +|**URL** | :literal:`/config` | ++--------------------+---------------------------------------------------------------+ +|**Method** | **GET** | ++--------------------+---------------------------------------------------------------+ +|**URL Params** | none | ++--------------------+---------------------------------------------------------------+ +|**Data Params** | none | ++--------------------+---------------------------------------------------------------+ +|**Success Response**| {"section":{"option":"*value*",...},...} | ++--------------------+---------------------------------------------------------------+ +|**Error Response** | {"error":"*error_desc*"} | ++--------------------+---------------------------------------------------------------+ + +| + ++--------------------+---------------------------------------------------------------+ +|**Title** | Returns only a specific section | ++--------------------+---------------------------------------------------------------+ +|**URL** | ``/config/'section'`` | ++--------------------+---------------------------------------------------------------+ +|**Method** | **GET** | ++--------------------+---------------------------------------------------------------+ +|**URL Params** | none | ++--------------------+---------------------------------------------------------------+ +|**Data Params** | none | ++--------------------+---------------------------------------------------------------+ +|**Success Response**| {"option":"*value*",...} | ++--------------------+---------------------------------------------------------------+ +|**Error Response** | {"error":"*error_desc*"} | ++--------------------+---------------------------------------------------------------+ + + +POST Request +------------ + ++--------------------+---------------------------------------------------------------+ +|**Title** | Creates/modifies options in the config | ++--------------------+---------------------------------------------------------------+ +|**URL** | :literal:`/config` | ++--------------------+---------------------------------------------------------------+ +|**Method** | **POST** | ++--------------------+---------------------------------------------------------------+ +|**URL Params** | none | ++--------------------+---------------------------------------------------------------+ +|**Data Params** | {"'section'": {"'option'": "'value'",...},...} | ++--------------------+---------------------------------------------------------------+ +|**Success Response**| Response Code: ``b) 200 OK`` | ++--------------------+---------------------------------------------------------------+ +|**Error Response** | | {"error":"*error_desc*"} | ++--------------------+---------------------------------------------------------------+ + + +OPTIONS Request +--------------- + ++--------------------+---------------------------------------------------------------+ +|**Title** | Gets request options | ++--------------------+---------------------------------------------------------------+ +|**URL** | :literal:`/config` | ++--------------------+---------------------------------------------------------------+ +|**Method** | **OPTIONS** | ++--------------------+---------------------------------------------------------------+ +|**URL Params** | none | ++--------------------+---------------------------------------------------------------+ +|**Data Params** | none | ++--------------------+---------------------------------------------------------------+ +|**Success Response**| | ++--------------------+---------------------------------------------------------------+ +|**Error Response** | none | ++--------------------+---------------------------------------------------------------+ diff --git a/man_developers/rest/gns.rst b/man_developers/rest/gns.rst @@ -0,0 +1,71 @@ +.. _ref-type: + +GNS API Service +=============== + +Definition +~~~~~~~~~~ + +Variables in single quotes ``'...'`` can or must be changed according to your specific case. + +``lookup`` is the combination of the ``record_name`` of a :ref:`ref-gnsrecord` and the ``name`` of the zone (or identity): ``record_name.name`` + +``type`` is the record_type of a :ref:`ref-gnsrecord`. + +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) Record not found - GNS record was not found, this is combined with the HTTP Error Code 404 Not Found + +Error ``1)`` is always possible and is not listed in following requests. + +Requests +~~~~~~~~ + +GET Request +----------- + +For this request ``record_type`` is optional. If missing or called with an invalid record_type, it will automatically be set to ANY. + +The success response is a :ref:`ref-gnsrecord` without its record_name. + ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ +|**Title** |Return all records for given name | ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ +|**URL** |:literal:`/gns/'lookup'?record_type='type'` | ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ +|**Method** |**GET** | ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ +|**Data Params** |none | ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ +|**Success Response**| [{"value": "*value*", "record_type": "*type*", "expiration_time": "*time*", "flag": *flag*},...] | ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ +|**Error Response** | {"error":"*error_desc*"} :sup:`2` | ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ + +OPTIONS Request +--------------- + ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ +|**Title** |Get request options | ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ +|**URL** |:literal:`/gns` | ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ +|**Method** |**OPTIONS** | ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ +|**URL Params** |none | ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ +|**Data Params** |none | ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ +|**Success Response**| | ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ +|**Error Response** |none | ++--------------------+----------------------------------------------------------------------------------------------------------------------------+ diff --git a/man_developers/rest/identity.rst b/man_developers/rest/identity.rst @@ -0,0 +1,216 @@ +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 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*"}`` + +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, 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 +------------ + ++--------------------+---------------------------------------------------------------+ +|**Title** |Returns all identities with name and public key | ++--------------------+---------------------------------------------------------------+ +|**URL** |:literal:`/identity/all` | ++--------------------+---------------------------------------------------------------+ +|**Method** |**GET** | ++--------------------+---------------------------------------------------------------+ +|**URL Params** |none | ++--------------------+---------------------------------------------------------------+ +|**Data Params** |none | ++--------------------+---------------------------------------------------------------+ +|**Success Response**|[{"pubkey":"*public_key*", "name":"*name*"},...] | ++--------------------+---------------------------------------------------------------+ +|**Error Response** | {"error":"*error_desc*"} :sup:`2` | ++--------------------+---------------------------------------------------------------+ +|**Attention** | The response in this request is an array! | ++--------------------+---------------------------------------------------------------+ + +| + ++--------------------+----------------------------------------------------------------+ +|**Title** |Returns only a specific identity | ++--------------------+----------------------------------------------------------------+ +|**URL** | ``/identity/pubkey/'public_key'`` or ``/identity/name/'name'`` | ++--------------------+----------------------------------------------------------------+ +|**Method** |**GET** | ++--------------------+----------------------------------------------------------------+ +|**URL Params** |none | ++--------------------+----------------------------------------------------------------+ +|**Data Params** |none | ++--------------------+----------------------------------------------------------------+ +|**Success Response**|{"pubkey":"*public_key*", "name":"*name*"} | ++--------------------+----------------------------------------------------------------+ +|**Error Response** | {"error":"*error_desc*"} :sup:`2; 3 or 4` | ++--------------------+----------------------------------------------------------------+ + +| + ++--------------------+---------------------------------------------------------------+ +|**Title** |Returns default identity for specific subsystem | ++--------------------+---------------------------------------------------------------+ +|**URL** |:literal:`/identity/subsystem/'subsystem'` | ++--------------------+---------------------------------------------------------------+ +|**Method** |**GET** | ++--------------------+---------------------------------------------------------------+ +|**URL Params** |none | ++--------------------+---------------------------------------------------------------+ +|**Data Params** |none | ++--------------------+---------------------------------------------------------------+ +|**Success Response**|{"pubkey":"*public_key*", "name":"*name*"} | ++--------------------+---------------------------------------------------------------+ +|**Error Response** | {"error":"*error_desc*"} :sup:`2; 5` | ++--------------------+---------------------------------------------------------------+ + +POST Request +------------ + ++--------------------+---------------------------------------------------------------+ +|**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** | | {"error":"*error_desc*"} :sup:`6; 7` | +| | | *or* | +| | | Response Code: ``e) 409 Conflict`` if name in use | ++--------------------+---------------------------------------------------------------+ + +PUT Request +----------- + ++--------------------+----------------------------------------------------------------+ +|**Title** |Changes name of identity | ++--------------------+----------------------------------------------------------------+ +|**URL** | ``/identity/pubkey/'public_key'`` or ``/identity/name/'name'`` | ++--------------------+----------------------------------------------------------------+ +|**Method** |**PUT** | ++--------------------+----------------------------------------------------------------+ +|**URL Params** |none | ++--------------------+----------------------------------------------------------------+ +|**Data Params** | {"newname":'*newname*'} | ++--------------------+----------------------------------------------------------------+ +|**Success Response**| Response Code: :literal:`c) 204 No Content` | ++--------------------+----------------------------------------------------------------+ +|**Error Response** | | {"error":"*error_desc*"} :sup:`2; 3 or 4; 6; 7; 8` | +| | | *or* | +| | | Response Code: :literal:`e) 409 Conflict` if newname in use | ++--------------------+----------------------------------------------------------------+ + +| + ++--------------------+----------------------------------------------------------------+ +|**Title** |Sets identity as default for a subsystem | ++--------------------+----------------------------------------------------------------+ +|**URL** | ``/identity/subsystem/'name'`` | ++--------------------+----------------------------------------------------------------+ +|**Method** |**PUT** | ++--------------------+----------------------------------------------------------------+ +|**URL Params** |none | ++--------------------+----------------------------------------------------------------+ +|**Data Params** | {"subsystem":'*subsystem*'} | ++--------------------+----------------------------------------------------------------+ +|**Success Response**| Response Code: :literal:`c) 204 No Content` | ++--------------------+----------------------------------------------------------------+ +|**Error Response** | {"error":"*error_desc*"} :sup:`2; 4; 6; 7; 9` | ++--------------------+----------------------------------------------------------------+ + +DELETE Request +-------------- + ++--------------------+----------------------------------------------------------------+ +|**Title** |Deletes specific identity | ++--------------------+----------------------------------------------------------------+ +|**URL** | ``/identity/pubkey/'public_key'`` or ``/identity/name/'name'`` | ++--------------------+----------------------------------------------------------------+ +|**Method** |**DELETE** | ++--------------------+----------------------------------------------------------------+ +|**URL Params** |none | ++--------------------+----------------------------------------------------------------+ +|**Data Params** |none | ++--------------------+----------------------------------------------------------------+ +|**Success Response**| Response Code: :literal:`c) 204 No Content` | ++--------------------+----------------------------------------------------------------+ +|**Error Response** | {"error":"*error_desc*"} :sup:`2; 3 or 4` | ++--------------------+----------------------------------------------------------------+ + +OPTIONS Request +--------------- + ++--------------------+----------------------------------------------------------------+ +|**Title** |Gets request options | ++--------------------+----------------------------------------------------------------+ +|**URL** |:literal:`/identity` | ++--------------------+----------------------------------------------------------------+ +|**Method** |**OPTIONS** | ++--------------------+----------------------------------------------------------------+ +|**URL Params** |none | ++--------------------+----------------------------------------------------------------+ +|**Data Params** |none | ++--------------------+----------------------------------------------------------------+ +|**Success Response**| | ++--------------------+----------------------------------------------------------------+ +|**Error Response** |none | ++--------------------+----------------------------------------------------------------+ diff --git a/man_developers/rest/index.rst b/man_developers/rest/index.rst @@ -0,0 +1,80 @@ +REST API +======== + +Configuration +~~~~~~~~~~~~~ + +In order to start the REST service, execute: + +:: + + $ gnunet-arm -i rest + +The REST service will listen by default on port 7776. +The service is run by each user so you may have to modify the port accordingly: + +:: + + $ gnunet-config -s rest -o HTTP_PORT -V 7788 + +Note that you may need to authenticate agains the API using HTTP basic authentication. +The REST service autogenerates a password upon first launch. +You can inspect your user-specific authentication secret by executing: + +:: + + $ cat $(gnunet-config -f -s rest -o BASIC_AUTH_SECRET_FILE) + +To access the REST API, you can use any HTTP client such as a browser or cURL: + +:: + + $ curl localhost:7776/identity -u<username>:<secret> + +You may disable the authentication if you want to by executing: + +:: + + $ gnunet-config -s rest -o BASIC_AUTH_ENABLED -V NO + +However, disabling authentication is not recommended. + +Conventions +~~~~~~~~~~~ + +The GNUnet Web API is based in REST principles. Data resources are accessed via HTTP requests to an API endpoint. Where possible, the Web API uses the following HTTP methods for each action: + ++----------+-----------------------------+ +|**Method**|**Action** | ++==========+=============================+ +|GET |Retrieve object(s) | ++----------+-----------------------------+ +|POST |Create new object(s) | ++----------+-----------------------------+ +|PUT |Edit existing object(s) | ++----------+-----------------------------+ +|DELETE |Delete existing object(s) | ++----------+-----------------------------+ +|OPTIONS |Get allowed headers | ++----------+-----------------------------+ + +Services +~~~~~~~~ + +.. toctree:: + :maxdepth: 3 + :caption: Contents: + + identity + namestore + gns + peerinfo + config + + + +====== +Search +====== + +* :ref:`search` diff --git a/man_developers/rest/namestore.rst b/man_developers/rest/namestore.rst @@ -0,0 +1,188 @@ +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 | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ diff --git a/man_developers/rest/peerinfo.rst b/man_developers/rest/peerinfo.rst @@ -0,0 +1,98 @@ +Peerinfo API Service +==================== + +Definition +~~~~~~~~~~ + +Variables in single quotes ``'...'`` can or must be changed according to your specific case. + +``friend`` is to enable the optional friend information. It is either ``yes`` or can be left away. + +Peer +---- + +A peer consists of an ``identifier`` and one or more ``addresses`` with ``expiration dates``. + +Peerinfo Response +----------------- + +The response of the peerinfo API is a JSON Array:: + + [ + { + "peer":'identifier', + "array": [ + { + "address":'peer_address', + "expires":'address_expiration' + }, + ... + ] + }, + ... + ] + +``ìdentifier`` is a 52-character, alphanumeric identifier of the peer. + +``peer_address`` is one URI as string. + +``address_expiration`` is the date, when the address expires, e.g. "Wed Aug 1 10:00:00 2018". + + +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 peers found - Peers were not found, 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 Peerinfo 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 peers and resolves their addresses | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ +|**URL** | :literal:`/peerinfo` | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ +|**Method** | **GET** | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ +|**URL Params** | ``?friend='friend'`` optional | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ +|**Data Params** | none | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ +|**Success Response**| Peerinfo Response *or* Response Code: ``500 Internal Server Error`` | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ +|**Error Response** | {"error":"*error_desc*"} :sup:`2` | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ + +OPTIONS Request +--------------- + ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ +|**Title** |Gets request options | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ +|**URL** |:literal:`/peerinfo` | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ +|**Method** |**OPTIONS** | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ +|**URL Params** |none | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ +|**Data Params** |none | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ +|**Success Response**| | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+ +|**Error Response** |none | ++--------------------+---------------------------------------------------------------------------------------------------------------------------+