diff options
| author | Phil <phil.buschmann@tum.de> | 2018-08-12 23:07:29 +0200 |
|---|---|---|
| committer | Phil <phil.buschmann@tum.de> | 2018-08-12 23:07:29 +0200 |
| commit | c4883a8df28fef1021b77f42348d601dddbc82ca (patch) | |
| tree | 4f32405fd6c7ce7aa87d60f65e1a0f6e87646807 | |
| parent | c89eef6cc42b6d7bfcfd761f1c9f7cf260c006e7 (diff) | |
| download | gnunet-rest-api-c4883a8df28fef1021b77f42348d601dddbc82ca.tar.gz gnunet-rest-api-c4883a8df28fef1021b77f42348d601dddbc82ca.zip | |
fix apis
| -rw-r--r-- | source/gns.rst | 97 | ||||
| -rw-r--r-- | source/identity.rst | 30 | ||||
| -rw-r--r-- | source/index.rst | 31 | ||||
| -rw-r--r-- | source/namestore.rst | 247 | ||||
| -rw-r--r-- | source/peerinfo.rst | 98 |
5 files changed, 305 insertions, 198 deletions
diff --git a/source/gns.rst b/source/gns.rst index 240a9d9..53c9872 100644 --- a/source/gns.rst +++ b/source/gns.rst | |||
| @@ -1,50 +1,71 @@ | |||
| 1 | .. _ref-type: | 1 | .. _ref-type: |
| 2 | 2 | ||
| 3 | GNUnet GNS API Service | 3 | GNS API Service |
| 4 | ====================== | 4 | =============== |
| 5 | |||
| 6 | Definition | ||
| 7 | ~~~~~~~~~~ | ||
| 5 | 8 | ||
| 6 | Variables in single quotes ``'...'`` can or must be changed according to your specific case. | 9 | Variables in single quotes ``'...'`` can or must be changed according to your specific case. |
| 7 | 10 | ||
| 8 | ``name`` is the name of an identity. | 11 | ``lookup`` is the combination of the ``record_name`` of a :ref:`ref-gnsrecord` and the ``name`` of the zone (or identity): ``record_name.name`` |
| 9 | 12 | ||
| 10 | ``record_type`` is the record_type. 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`` | 13 | ``type`` is the record_type of a :ref:`ref-gnsrecord`. |
| 11 | 14 | ||
| 12 | ============ | 15 | Error Response |
| 13 | GET Requests | 16 | -------------- |
| 14 | ============ | ||
| 15 | 17 | ||
| 16 | For this request ``record_type`` is optional. If called with an invalid record_type, it will automatically be set to ANY. | 18 | An error response is sent in the JSON format: ``{"error":"*error_description*"}`` |
| 17 | 19 | ||
| 18 | +--------------------+--------------------------------------------------------------------------------------------------------------+ | 20 | Following numbers are added for references inside the documentation only. |
| 19 | |**Title** |Return all records for given name | | 21 | |
| 20 | +--------------------+--------------------------------------------------------------------------------------------------------------+ | 22 | Error descriptions are:: |
| 21 | |**URL** |:literal:`/gns?name='name'&record_type='record_type'` | | 23 | |
| 22 | +--------------------+--------------------------------------------------------------------------------------------------------------+ | 24 | Nr. Error Description - Explanation |
| 23 | |**Method** |**GET** | | 25 | 1) Unknown Error - Error is not specified |
| 24 | +--------------------+--------------------------------------------------------------------------------------------------------------+ | 26 | 2) Record not found - GNS record was not found, this is combined with the HTTP Error Code 404 Not Found |
| 25 | |**Data Params** |none | | 27 | |
| 26 | +--------------------+--------------------------------------------------------------------------------------------------------------+ | 28 | Error ``1)`` is always possible and is not listed in following requests. |
| 27 | |**Success Response**| [{"value": "*value*", "type": "*type*", "expiration_time": "*time*", "flag": *flag*, "label": "*name*"},...] | | 29 | |
| 28 | +--------------------+--------------------------------------------------------------------------------------------------------------+ | 30 | Requests |
| 29 | |**Error Response** |{"error":"*error_desc*"} | | 31 | ~~~~~~~~ |
| 30 | +--------------------+--------------------------------------------------------------------------------------------------------------+ | 32 | |
| 33 | GET Request | ||
| 34 | ----------- | ||
| 35 | |||
| 36 | For this request ``record_type`` is optional. If missing or called with an invalid record_type, it will automatically be set to ANY. | ||
| 37 | |||
| 38 | The success response is a :ref:`ref-gnsrecord` without its record_name. | ||
| 39 | |||
| 40 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ | ||
| 41 | |**Title** |Return all records for given name | | ||
| 42 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ | ||
| 43 | |**URL** |:literal:`/gns/'lookup'?record_type='type'` | | ||
| 44 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ | ||
| 45 | |**Method** |**GET** | | ||
| 46 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ | ||
| 47 | |**Data Params** |none | | ||
| 48 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ | ||
| 49 | |**Success Response**| [{"value": "*value*", "record_type": "*type*", "expiration_time": "*time*", "flag": *flag*},...] | | ||
| 50 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ | ||
| 51 | |**Error Response** | {"error":"*error_desc*"} :sup:`2` | | ||
| 52 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ | ||
| 31 | 53 | ||
| 32 | =============== | ||
| 33 | OPTIONS Request | 54 | OPTIONS Request |
| 34 | =============== | 55 | --------------- |
| 35 | 56 | ||
| 36 | +--------------------+---------------------------------------------------------+ | 57 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ |
| 37 | |**Title** |Get request options | | 58 | |**Title** |Get request options | |
| 38 | +--------------------+---------------------------------------------------------+ | 59 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ |
| 39 | |**URL** |:literal:`/gns` | | 60 | |**URL** |:literal:`/gns` | |
| 40 | +--------------------+---------------------------------------------------------+ | 61 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ |
| 41 | |**Method** |**OPTIONS** | | 62 | |**Method** |**OPTIONS** | |
| 42 | +--------------------+---------------------------------------------------------+ | 63 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ |
| 43 | |**URL Params** |none | | 64 | |**URL Params** |none | |
| 44 | +--------------------+---------------------------------------------------------+ | 65 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ |
| 45 | |**Data Params** |none | | 66 | |**Data Params** |none | |
| 46 | +--------------------+---------------------------------------------------------+ | 67 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ |
| 47 | |**Success Response**| | | 68 | |**Success Response**| | |
| 48 | +--------------------+---------------------------------------------------------+ | 69 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ |
| 49 | |**Error Response** |none | | 70 | |**Error Response** |none | |
| 50 | +--------------------+---------------------------------------------------------+ | 71 | +--------------------+----------------------------------------------------------------------------------------------------------------------------+ |
diff --git a/source/identity.rst b/source/identity.rst index 11b2d29..63dd2e7 100644 --- a/source/identity.rst +++ b/source/identity.rst | |||
| @@ -1,8 +1,8 @@ | |||
| 1 | GNUnet Identity API Service | 1 | Identity API Service |
| 2 | =========================== | 2 | ==================== |
| 3 | 3 | ||
| 4 | Definition | 4 | Definition |
| 5 | ========== | 5 | ~~~~~~~~~~ |
| 6 | 6 | ||
| 7 | Variables in single quotes ``'...'`` can or must be changed according to your specific case. | 7 | Variables in single quotes ``'...'`` can or must be changed according to your specific case. |
| 8 | 8 | ||
| @@ -25,7 +25,7 @@ Error Response | |||
| 25 | 25 | ||
| 26 | An error response is sent in the JSON format: ``{"error":"*error_description*"}`` | 26 | An error response is sent in the JSON format: ``{"error":"*error_description*"}`` |
| 27 | 27 | ||
| 28 | Numbers are added for references inside the documentation only. | 28 | Following numbers are added for references inside the documentation only. |
| 29 | 29 | ||
| 30 | Error descriptions are:: | 30 | Error descriptions are:: |
| 31 | 31 | ||
| @@ -58,7 +58,7 @@ A response of a message has a HTTP response code. Usually, this code is 200 OK f | |||
| 58 | ``d) 404 Not Found`` is always used when the error message is either ``2)``, ``3)`` or ``4)``. | 58 | ``d) 404 Not Found`` is always used when the error message is either ``2)``, ``3)`` or ``4)``. |
| 59 | 59 | ||
| 60 | Requests | 60 | Requests |
| 61 | ======== | 61 | ~~~~~~~~ |
| 62 | 62 | ||
| 63 | GET Requests | 63 | GET Requests |
| 64 | ------------ | 64 | ------------ |
| @@ -76,7 +76,7 @@ GET Requests | |||
| 76 | +--------------------+---------------------------------------------------------------+ | 76 | +--------------------+---------------------------------------------------------------+ |
| 77 | |**Success Response**|[{"pubkey":"*public_key*", "name":"*name*"},...] | | 77 | |**Success Response**|[{"pubkey":"*public_key*", "name":"*name*"},...] | |
| 78 | +--------------------+---------------------------------------------------------------+ | 78 | +--------------------+---------------------------------------------------------------+ |
| 79 | |**Error Response** | ``2) No identity found`` | | 79 | |**Error Response** | {"error":"*error_desc*"} :sup:`2` | |
| 80 | +--------------------+---------------------------------------------------------------+ | 80 | +--------------------+---------------------------------------------------------------+ |
| 81 | |**Attention** | The response in this request is an array! | | 81 | |**Attention** | The response in this request is an array! | |
| 82 | +--------------------+---------------------------------------------------------------+ | 82 | +--------------------+---------------------------------------------------------------+ |
| @@ -96,8 +96,7 @@ GET Requests | |||
| 96 | +--------------------+----------------------------------------------------------------+ | 96 | +--------------------+----------------------------------------------------------------+ |
| 97 | |**Success Response**|{"pubkey":"*public_key*", "name":"*name*"} | | 97 | |**Success Response**|{"pubkey":"*public_key*", "name":"*name*"} | |
| 98 | +--------------------+----------------------------------------------------------------+ | 98 | +--------------------+----------------------------------------------------------------+ |
| 99 | |**Error Response** | | ``2) No identity found``; ``3) Missing identity public key`` | | 99 | |**Error Response** | {"error":"*error_desc*"} :sup:`2; 3 or 4` | |
| 100 | | | | or ``4) Missing identity name`` | | ||
| 101 | +--------------------+----------------------------------------------------------------+ | 100 | +--------------------+----------------------------------------------------------------+ |
| 102 | 101 | ||
| 103 | | | 102 | | |
| @@ -115,7 +114,7 @@ GET Requests | |||
| 115 | +--------------------+---------------------------------------------------------------+ | 114 | +--------------------+---------------------------------------------------------------+ |
| 116 | |**Success Response**|{"pubkey":"*public_key*", "name":"*name*"} | | 115 | |**Success Response**|{"pubkey":"*public_key*", "name":"*name*"} | |
| 117 | +--------------------+---------------------------------------------------------------+ | 116 | +--------------------+---------------------------------------------------------------+ |
| 118 | |**Error Response** | ``2) No identity found``; ``5) Missing subsystem name`` | | 117 | |**Error Response** | {"error":"*error_desc*"} :sup:`2; 5` | |
| 119 | +--------------------+---------------------------------------------------------------+ | 118 | +--------------------+---------------------------------------------------------------+ |
| 120 | 119 | ||
| 121 | POST Request | 120 | POST Request |
| @@ -134,7 +133,7 @@ POST Request | |||
| 134 | +--------------------+---------------------------------------------------------------+ | 133 | +--------------------+---------------------------------------------------------------+ |
| 135 | |**Success Response**| Response Code: :literal:` b) 201 Created` | | 134 | |**Success Response**| Response Code: :literal:` b) 201 Created` | |
| 136 | +--------------------+---------------------------------------------------------------+ | 135 | +--------------------+---------------------------------------------------------------+ |
| 137 | |**Error Response** | | ``6) No data``; ``7) Data invalid`` | | 136 | |**Error Response** | | {"error":"*error_desc*"} :sup:`6; 7` | |
| 138 | | | | *or* | | 137 | | | | *or* | |
| 139 | | | | Response Code: ``e) 409 Conflict`` if name in use | | 138 | | | | Response Code: ``e) 409 Conflict`` if name in use | |
| 140 | +--------------------+---------------------------------------------------------------+ | 139 | +--------------------+---------------------------------------------------------------+ |
| @@ -155,9 +154,7 @@ PUT Request | |||
| 155 | +--------------------+----------------------------------------------------------------+ | 154 | +--------------------+----------------------------------------------------------------+ |
| 156 | |**Success Response**| Response Code: :literal:`c) 204 No Content` | | 155 | |**Success Response**| Response Code: :literal:`c) 204 No Content` | |
| 157 | +--------------------+----------------------------------------------------------------+ | 156 | +--------------------+----------------------------------------------------------------+ |
| 158 | |**Error Response** | | ``2) No identity found``; ``3) Missing identity public key`` | | 157 | |**Error Response** | | {"error":"*error_desc*"} :sup:`2; 3 or 4; 6; 7; 8` | |
| 159 | | | | or ``4) Missing identity name``; ``6) No data``; | | ||
| 160 | | | | ``7) Data invalid``; ``8) Rename failed`` | | ||
| 161 | | | | *or* | | 158 | | | | *or* | |
| 162 | | | | Response Code: :literal:`e) 409 Conflict` if newname in use | | 159 | | | | Response Code: :literal:`e) 409 Conflict` if newname in use | |
| 163 | +--------------------+----------------------------------------------------------------+ | 160 | +--------------------+----------------------------------------------------------------+ |
| @@ -177,9 +174,7 @@ PUT Request | |||
| 177 | +--------------------+----------------------------------------------------------------+ | 174 | +--------------------+----------------------------------------------------------------+ |
| 178 | |**Success Response**| Response Code: :literal:`c) 204 No Content` | | 175 | |**Success Response**| Response Code: :literal:`c) 204 No Content` | |
| 179 | +--------------------+----------------------------------------------------------------+ | 176 | +--------------------+----------------------------------------------------------------+ |
| 180 | |**Error Response** | | ``2) No identity found``; ``4) Missing identity name``; | | 177 | |**Error Response** | {"error":"*error_desc*"} :sup:`2; 4; 6; 7; 9` | |
| 181 | | | | ``6) No data``; ``7) Data invalid``; | | ||
| 182 | | | | ``9) Setting subsystem failed`` | | ||
| 183 | +--------------------+----------------------------------------------------------------+ | 178 | +--------------------+----------------------------------------------------------------+ |
| 184 | 179 | ||
| 185 | DELETE Request | 180 | DELETE Request |
| @@ -198,8 +193,7 @@ DELETE Request | |||
| 198 | +--------------------+----------------------------------------------------------------+ | 193 | +--------------------+----------------------------------------------------------------+ |
| 199 | |**Success Response**| Response Code: :literal:`c) 204 No Content` | | 194 | |**Success Response**| Response Code: :literal:`c) 204 No Content` | |
| 200 | +--------------------+----------------------------------------------------------------+ | 195 | +--------------------+----------------------------------------------------------------+ |
| 201 | |**Error Response** | | ``2) No identity found``; ``3) Missing identity public key`` | | 196 | |**Error Response** | {"error":"*error_desc*"} :sup:`2; 3 or 4` | |
| 202 | | | | or ``4) Missing identity name`` | | ||
| 203 | +--------------------+----------------------------------------------------------------+ | 197 | +--------------------+----------------------------------------------------------------+ |
| 204 | 198 | ||
| 205 | OPTIONS Request | 199 | OPTIONS Request |
diff --git a/source/index.rst b/source/index.rst index 3f41bb9..4fc373e 100644 --- a/source/index.rst +++ b/source/index.rst | |||
| @@ -3,18 +3,18 @@ | |||
| 3 | You can adapt this file completely to your liking, but it should at least | 3 | You can adapt this file completely to your liking, but it should at least |
| 4 | contain the root `toctree` directive. | 4 | contain the root `toctree` directive. |
| 5 | 5 | ||
| 6 | Welcome to GNUnet REST API's documentation! | 6 | Welcome to the REST API's documentation! |
| 7 | =========================================== | 7 | ======================================== |
| 8 | 8 | ||
| 9 | ======== | 9 | |
| 10 | Requests | 10 | REST API |
| 11 | ======== | 11 | ~~~~~~~~ |
| 12 | 12 | ||
| 13 | 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: | 13 | 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: |
| 14 | 14 | ||
| 15 | +----------+-----------------------------+ | 15 | +----------+-----------------------------+ |
| 16 | |**Method**|**Action** | | 16 | |**Method**|**Action** | |
| 17 | +----------+-----------------------------+ | 17 | +==========+=============================+ |
| 18 | |GET |Retrieve object(s) | | 18 | |GET |Retrieve object(s) | |
| 19 | +----------+-----------------------------+ | 19 | +----------+-----------------------------+ |
| 20 | |POST |Create new object(s) | | 20 | |POST |Create new object(s) | |
| @@ -23,22 +23,25 @@ The GNUnet Web API is based in REST principles. Data resources are accessed via | |||
| 23 | +----------+-----------------------------+ | 23 | +----------+-----------------------------+ |
| 24 | |DELETE |Delete existing object(s) | | 24 | |DELETE |Delete existing object(s) | |
| 25 | +----------+-----------------------------+ | 25 | +----------+-----------------------------+ |
| 26 | |OPTIONS |Get allowed headers | | ||
| 27 | +----------+-----------------------------+ | ||
| 26 | 28 | ||
| 29 | Services | ||
| 30 | ~~~~~~~~ | ||
| 27 | 31 | ||
| 28 | .. toctree:: | 32 | .. toctree:: |
| 29 | :maxdepth: 2 | 33 | :maxdepth: 3 |
| 30 | :caption: Contents: | 34 | :caption: Contents: |
| 31 | 35 | ||
| 32 | identity | 36 | identity |
| 33 | gns | ||
| 34 | namestore | 37 | namestore |
| 38 | gns | ||
| 39 | peerinfo | ||
| 35 | 40 | ||
| 36 | 41 | ||
| 37 | 42 | ||
| 38 | ================== | 43 | ====== |
| 39 | Indices and tables | 44 | Search |
| 40 | ================== | 45 | ====== |
| 41 | 46 | ||
| 42 | * :ref:`genindex` | ||
| 43 | * :ref:`modindex` | ||
| 44 | * :ref:`search` | 47 | * :ref:`search` |
diff --git a/source/namestore.rst b/source/namestore.rst index cd2be42..85aba3a 100644 --- a/source/namestore.rst +++ b/source/namestore.rst | |||
| @@ -1,34 +1,65 @@ | |||
| 1 | GNUnet Namestore API Service | 1 | Namestore API Service |
| 2 | ============================ | 2 | ===================== |
| 3 | |||
| 4 | Definition | ||
| 5 | ~~~~~~~~~~ | ||
| 3 | 6 | ||
| 4 | Variables in single quotes ``'...'`` can or must be changed according to your specific case. | 7 | Variables in single quotes ``'...'`` can or must be changed according to your specific case. |
| 5 | 8 | ||
| 6 | Namestore communicates with GNS records: | 9 | ``name`` is the name of a zone. A zone is the name of an identity in this case. |
| 10 | |||
| 11 | .. _ref-gnsrecord: | ||
| 12 | |||
| 13 | GNS Record | ||
| 14 | ---------- | ||
| 15 | |||
| 16 | Namestore entries are GNS records. GNS records have a ``record_type``, a ``value``, an ``expiration_time``, a ``flag`` and a ``record_name``. | ||
| 17 | Adding a GNS records with the same record_name overwrites the old GNS record. | ||
| 7 | 18 | ||
| 8 | ``type`` is the type of the record, e.g. "PKEY" for private key. Possible types are listed in :ref:`ref-type`. | 19 | A GNS record is sent in the JSON format: ``{"value": "value", "record_type": "type", "expiration_time": "time", "flag": flag, "record_name": "rname"}`` |
| 20 | |||
| 21 | ``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`` | ||
| 9 | 22 | ||
| 10 | ``value`` is the value of the specific type of the record, e.g. the private key of an identity. | 23 | ``value`` is the value of the specific type of the record, e.g. the private key of an identity. |
| 11 | 24 | ||
| 12 | ``time`` is the expiration time of the record either "never" or fancy time (see GNUNET_STRINGS_fancy_time_to_absolute) | 25 | ``time`` is the expiration time of the record either "never" or fancy time (see GNUNET_STRINGS_fancy_time_to_absolute) |
| 13 | 26 | ||
| 14 | ``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 | 27 | ``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. |
| 28 | |||
| 29 | ``rname`` is the name of the record. | ||
| 30 | |||
| 31 | Error Response | ||
| 32 | -------------- | ||
| 15 | 33 | ||
| 16 | ``label`` is the name of the record. No duplicates are allowed. | 34 | An error response is sent in the JSON format: ``{"error":"*error_description*"}`` |
| 17 | 35 | ||
| 18 | Other variables used in the requests: | 36 | Following numbers are added for references inside the documentation only. |
| 19 | 37 | ||
| 20 | ``error_desc`` is the description of the returned error. | 38 | Error descriptions are:: |
| 39 | |||
| 40 | Nr. Error Description - Explanation | ||
| 41 | 1) Unknown Error - Error is not specified | ||
| 42 | 2) No identity found - Identity was not found with given name, this is combined with the HTTP Error Code 404 Not Found | ||
| 43 | 3) No default zone specified - Identity name was not given and no identiy was added to the subsystem namestore | ||
| 44 | 4) Namestore action failed - The task of the namestore API (not REST API) failed | ||
| 45 | 5) No data - Missing data | ||
| 46 | 6) Data invalid - Wrong data given | ||
| 47 | 7) Error storing records - POST request failed | ||
| 48 | 8) Deleting record failed - DELETE request failed | ||
| 49 | 9) No record found - Delete failed due to missing record, this is combined with the HTTP Error Code 404 Not Found | ||
| 21 | 50 | ||
| 22 | ``public_key`` is the public key of an identity. | 51 | Error ``1)`` is always possible and is not listed in following requests. |
| 23 | 52 | ||
| 24 | ``name`` is the name of an identity. | 53 | 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. |
| 25 | 54 | ||
| 55 | Requests | ||
| 56 | ~~~~~~~~ | ||
| 26 | 57 | ||
| 27 | GET Request | 58 | GET Request |
| 28 | ------------ | 59 | ------------ |
| 29 | 60 | ||
| 30 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 61 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 31 | |**Title** |Returns all namestore entries from all zones | | 62 | |**Title** |Returns all namestore entries of default identity | |
| 32 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 63 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 33 | |**URL** |:literal:`/namestore` | | 64 | |**URL** |:literal:`/namestore` | |
| 34 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 65 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| @@ -38,17 +69,17 @@ GET Request | |||
| 38 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 69 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 39 | |**Data Params** |none | | 70 | |**Data Params** |none | |
| 40 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 71 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 41 | |**Success Response**|[{"value": "*value*", "type": "*type*", "expiration_time": "*time*", "flag": *flag*, "label": "*name*"},...] | | 72 | |**Success Response**|[{"value": "*value*", "record_type": "*type*", "expiration_time": "*time*", "flag": *flag*, "record_name": "*rname*"},...] | |
| 42 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 73 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 43 | |**Error Response** |{"error":"*error_desc*"} | | 74 | |**Error Response** | {"error":"*error_desc*"} :sup:`3; 4` | |
| 44 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 75 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 45 | 76 | ||
| 46 | | | 77 | | |
| 47 | 78 | ||
| 48 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 79 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 49 | |**Title** |Returns all namestore entries for one zone specified by its public key | | 80 | |**Title** |Returns all namestore entries for one zone specified by its name | |
| 50 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 81 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 51 | |**URL** |:literal:`/namestore?pubkey='pubkey'` | | 82 | |**URL** |:literal:`/namestore/'name'` | |
| 52 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 83 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 53 | |**Method** |**GET** | | 84 | |**Method** |**GET** | |
| 54 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 85 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| @@ -56,142 +87,102 @@ GET Request | |||
| 56 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 87 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 57 | |**Data Params** |none | | 88 | |**Data Params** |none | |
| 58 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 89 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 59 | |**Success Response**|[{"value": "*value*", "type": "*type*", "expiration_time": "*time*", "flag": *flag*, "label": "*name*"},...] | | 90 | |**Success Response**|[{"value": "*value*", "record_type": "*type*", "expiration_time": "*time*", "flag": *flag*, "record_name": "*rname*"},...] | |
| 60 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 91 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 61 | |**Error Response** |{"error":"*error_desc*"} | | 92 | |**Error Response** | {"error":"*error_desc*"} :sup:`2; 4` | |
| 62 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 93 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 63 | 94 | ||
| 64 | | | 95 | POST Request |
| 96 | ------------ | ||
| 65 | 97 | ||
| 66 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 98 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 67 | |**Title** |Returns all namestore entries for one zone specified by its name | | 99 | |**Title** |Creates a namestore entry for default identity | |
| 68 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 100 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 69 | |**URL** |:literal:`/namestore?name='name'` | | 101 | |**URL** |:literal:`/namestore` | |
| 70 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 102 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 71 | |**Method** |**GET** | | 103 | |**Method** |**POST** | |
| 72 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 104 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 73 | |**URL Params** |none | | 105 | |**URL Params** |none | |
| 74 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 106 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 75 | |**Data Params** |none | | 107 | |**Data Params** |{"value": "*value*", "record_type": "*type*", "expiration_time": "*time*", "flag": *flag*, "record_name": "*rname*"} | |
| 76 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 108 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 77 | |**Success Response**|[{"value": "*value*", "type": "*type*", "expiration_time": "*time*", "flag": *flag*, "label": "*name*"},...] | | 109 | |**Success Response**|Response Code: :literal:`204` (No Content) | |
| 78 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 110 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 79 | |**Error Response** |{"error":"*error_desc*"} | | 111 | |**Error Response** | {"error":"*error_desc*"} :sup:`3; 4; 5; 6; 7` | |
| 80 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | 112 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 81 | 113 | ||
| 82 | POST Request | ||
| 83 | ------------ | ||
| 84 | |||
| 85 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 86 | |**Title** |Creates a namestore entry | | ||
| 87 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 88 | |**URL** |:literal:`/namestore` | | ||
| 89 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 90 | |**Method** |**POST** | | ||
| 91 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 92 | |**URL Params** |none | | ||
| 93 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 94 | |**Data Params** |{"value": "*value*", "type": "*type*", "expiration_time": "*time*", "flag": *flag*, "label": "*name*"}| | ||
| 95 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 96 | |**Success Response**|Response Code: :literal:`204` (No Content) | | ||
| 97 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 98 | |**Error Response** | | {"error":"*error_desc*"} | | ||
| 99 | | | | *or* | | ||
| 100 | | | | Response Code: :literal:`409` (Conflict) | | ||
| 101 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 102 | |||
| 103 | | | 114 | | |
| 104 | 115 | ||
| 105 | +--------------------+------------------------------------------------------------------------------------------------------+ | 116 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 106 | |**Title** |Creates a namestore entry for one zone specified by its public key | | 117 | |**Title** |Creates a namestore entry for one zone specified by its name | |
| 107 | +--------------------+------------------------------------------------------------------------------------------------------+ | 118 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 108 | |**URL** |:literal:`/namestore?pubkey='pubkey'` | | 119 | |**URL** |:literal:`/namestore/'name'` | |
| 109 | +--------------------+------------------------------------------------------------------------------------------------------+ | 120 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 110 | |**Method** |**POST** | | 121 | |**Method** |**POST** | |
| 111 | +--------------------+------------------------------------------------------------------------------------------------------+ | 122 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 112 | |**URL Params** |none | | 123 | |**URL Params** |none | |
| 113 | +--------------------+------------------------------------------------------------------------------------------------------+ | 124 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 114 | |**Data Params** |{"value": "*value*", "type": "*type*", "expiration_time": "*time*", "flag": *flag*, "label": "*name*"}| | 125 | |**Data Params** |{"value": "*value*", "record_type": "*type*", "expiration_time": "*time*", "flag": *flag*, "record_name": "*rname*"} | |
| 115 | +--------------------+------------------------------------------------------------------------------------------------------+ | 126 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 116 | |**Success Response**|Response Code: :literal:`204` (No Content) | | 127 | |**Success Response**|Response Code: :literal:`204` (No Content) | |
| 117 | +--------------------+------------------------------------------------------------------------------------------------------+ | 128 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 118 | |**Error Response** | | {"error":"*error_desc*"} | | 129 | |**Error Response** | {"error":"*error_desc*"} :sup:`2; 4; 5; 6; 7` | |
| 119 | | | | *or* | | 130 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 120 | | | | Response Code: :literal:`409` (Conflict) | | ||
| 121 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 122 | |||
| 123 | | | ||
| 124 | |||
| 125 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 126 | |**Title** |Creates a namestore entry for one zone specified by its name | | ||
| 127 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 128 | |**URL** |:literal:`/namestore?name='name'` | | ||
| 129 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 130 | |**Method** |**POST** | | ||
| 131 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 132 | |**URL Params** |none | | ||
| 133 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 134 | |**Data Params** |{"value": "*value*", "type": "*type*", "expiration_time": "*time*", "flag": *flag*, "label": "*name*"}| | ||
| 135 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 136 | |**Success Response**|Response Code: :literal:`204` (No Content) | | ||
| 137 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 138 | |**Error Response** | | {"error":"*error_desc*"} | | ||
| 139 | | | | *or* | | ||
| 140 | | | | Response Code: :literal:`409` (Conflict) | | ||
| 141 | +--------------------+------------------------------------------------------------------------------------------------------+ | ||
| 142 | 131 | ||
| 143 | 132 | ||
| 144 | DELETE Request | 133 | DELETE Request |
| 145 | -------------- | 134 | -------------- |
| 146 | 135 | ||
| 147 | +--------------------+----------------------------------------------------+ | 136 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 148 | | **Title** | Deletes specific namestore entry | | 137 | | **Title** | Deletes specific namestore entry for default identity | |
| 149 | +--------------------+----------------------------------------------------+ | 138 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 150 | |**URL** |:literal:`/namestore?label='label'` | | 139 | |**URL** |:literal:`/namestore?record_name='rname'` | |
| 151 | +--------------------+----------------------------------------------------+ | 140 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 152 | |**Method** | **DELETE** | | 141 | |**Method** | **DELETE** | |
| 153 | +--------------------+----------------------------------------------------+ | 142 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 154 | |**URL Params** | none | | 143 | |**URL Params** | none | |
| 155 | +--------------------+----------------------------------------------------+ | 144 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 156 | |**Data Params** | none | | 145 | |**Data Params** | none | |
| 157 | +--------------------+----------------------------------------------------+ | 146 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 158 | |**Success Response**| Response Code: :literal:`204` (No Content) | | 147 | |**Success Response**| Response Code: :literal:`204` (No Content) | |
| 159 | +--------------------+----------------------------------------------------+ | 148 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 160 | |**Error Response** | {"error":"*error_desc*"} | | 149 | |**Error Response** | {"error":"*error_desc*"} :sup:`3; 4; 6; 8; 9` | |
| 161 | +--------------------+----------------------------------------------------+ | 150 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 162 | 151 | ||
| 163 | | | 152 | | |
| 164 | 153 | ||
| 165 | +--------------------+----------------------------------------------------+ | 154 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 166 | | **Title** | Deletes specific namestore entry in specific zone | | 155 | | **Title** | Deletes specific namestore entry in specific zone | |
| 167 | +--------------------+----------------------------------------------------+ | 156 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 168 | |**URL** |:literal:`/namestore?label='label'&pubkey='pubkey'` | | 157 | |**URL** |:literal:`/namestore/'name'?record_name='rname'` | |
| 169 | +--------------------+----------------------------------------------------+ | 158 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 170 | |**Method** | **DELETE** | | 159 | |**Method** | **DELETE** | |
| 171 | +--------------------+----------------------------------------------------+ | 160 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 172 | |**URL Params** | none | | 161 | |**URL Params** | none | |
| 173 | +--------------------+----------------------------------------------------+ | 162 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 174 | |**Data Params** | none | | 163 | |**Data Params** | none | |
| 175 | +--------------------+----------------------------------------------------+ | 164 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 176 | |**Success Response**| Response Code: :literal:`204` (No Content) | | 165 | |**Success Response**| Response Code: :literal:`204` (No Content) | |
| 177 | +--------------------+----------------------------------------------------+ | 166 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 178 | |**Error Response** | {"error":"*error_desc*"} | | 167 | |**Error Response** | {"error":"*error_desc*"} :sup:`2; 4; 6; 8; 9` | |
| 179 | +--------------------+----------------------------------------------------+ | 168 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 169 | |||
| 180 | 170 | ||
| 181 | | | 171 | OPTIONS Request |
| 172 | --------------- | ||
| 182 | 173 | ||
| 183 | +--------------------+----------------------------------------------------+ | 174 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 184 | | **Title** | Deletes specific namestore entry in specific zone | | 175 | |**Title** |Gets request options | |
| 185 | +--------------------+----------------------------------------------------+ | 176 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 186 | |**URL** |:literal:`/namestore?label='label'&name='name'` | | 177 | |**URL** |:literal:`/namestore` | |
| 187 | +--------------------+----------------------------------------------------+ | 178 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 188 | |**Method** | **DELETE** | | 179 | |**Method** |**OPTIONS** | |
| 189 | +--------------------+----------------------------------------------------+ | 180 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 190 | |**URL Params** | none | | 181 | |**URL Params** |none | |
| 191 | +--------------------+----------------------------------------------------+ | 182 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 192 | |**Data Params** | none | | 183 | |**Data Params** |none | |
| 193 | +--------------------+----------------------------------------------------+ | 184 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 194 | |**Success Response**| Response Code: :literal:`204` (No Content) | | 185 | |**Success Response**| | |
| 195 | +--------------------+----------------------------------------------------+ | 186 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
| 196 | |**Error Response** | {"error":"*error_desc*"} | | 187 | |**Error Response** |none | |
| 197 | +--------------------+----------------------------------------------------+ | 188 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ |
diff --git a/source/peerinfo.rst b/source/peerinfo.rst new file mode 100644 index 0000000..1d79a27 --- /dev/null +++ b/source/peerinfo.rst | |||
| @@ -0,0 +1,98 @@ | |||
| 1 | Peerinfo API Service | ||
| 2 | ==================== | ||
| 3 | |||
| 4 | Definition | ||
| 5 | ~~~~~~~~~~ | ||
| 6 | |||
| 7 | Variables in single quotes ``'...'`` can or must be changed according to your specific case. | ||
| 8 | |||
| 9 | ``friend`` is to enable the optional friend information. It is either ``yes`` or can be left away. | ||
| 10 | |||
| 11 | Peer | ||
| 12 | ---- | ||
| 13 | |||
| 14 | A peer consists of an ``identifier`` and one or more ``addresses`` with ``expiration dates``. | ||
| 15 | |||
| 16 | Peerinfo Response | ||
| 17 | ----------------- | ||
| 18 | |||
| 19 | The response of the peerinfo API is a JSON Array:: | ||
| 20 | |||
| 21 | [ | ||
| 22 | { | ||
| 23 | "peer":'identifier', | ||
| 24 | "array": [ | ||
| 25 | { | ||
| 26 | "address":'peer_address', | ||
| 27 | "expires":'address_expiration' | ||
| 28 | }, | ||
| 29 | ... | ||
| 30 | ] | ||
| 31 | }, | ||
| 32 | ... | ||
| 33 | ] | ||
| 34 | |||
| 35 | ``ìdentifier`` is a 52-character, alphanumeric identifier of the peer. | ||
| 36 | |||
| 37 | ``peer_address`` is one URI as string. | ||
| 38 | |||
| 39 | ``address_expiration`` is the date, when the address expires, e.g. "Wed Aug 1 10:00:00 2018". | ||
| 40 | |||
| 41 | |||
| 42 | Error Response | ||
| 43 | -------------- | ||
| 44 | |||
| 45 | An error response is sent in the JSON format: ``{"error":"*error_description*"}`` | ||
| 46 | |||
| 47 | Following numbers are added for references inside the documentation only. | ||
| 48 | |||
| 49 | Error descriptions are:: | ||
| 50 | |||
| 51 | Nr. Error Description - Explanation | ||
| 52 | 1) Unknown Error - Error is not specified | ||
| 53 | 2) No peers found - Peers were not found, this is combined with the HTTP Error Code 404 Not Found | ||
| 54 | |||
| 55 | Error ``1)`` is always possible and is not listed in following requests. | ||
| 56 | |||
| 57 | 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. | ||
| 58 | |||
| 59 | Requests | ||
| 60 | ~~~~~~~~ | ||
| 61 | |||
| 62 | GET Request | ||
| 63 | ------------ | ||
| 64 | |||
| 65 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 66 | |**Title** | Returns all peers and resolves their addresses | | ||
| 67 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 68 | |**URL** | :literal:`/peerinfo` | | ||
| 69 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 70 | |**Method** | **GET** | | ||
| 71 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 72 | |**URL Params** | ``?friend='friend'`` optional | | ||
| 73 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 74 | |**Data Params** | none | | ||
| 75 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 76 | |**Success Response**| Peerinfo Response *or* Response Code: ``500 Internal Server Error`` | | ||
| 77 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 78 | |**Error Response** | {"error":"*error_desc*"} :sup:`2` | | ||
| 79 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 80 | |||
| 81 | OPTIONS Request | ||
| 82 | --------------- | ||
| 83 | |||
| 84 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 85 | |**Title** |Gets request options | | ||
| 86 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 87 | |**URL** |:literal:`/peerinfo` | | ||
| 88 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 89 | |**Method** |**OPTIONS** | | ||
| 90 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 91 | |**URL Params** |none | | ||
| 92 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 93 | |**Data Params** |none | | ||
| 94 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 95 | |**Success Response**| | | ||
| 96 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||
| 97 | |**Error Response** |none | | ||
| 98 | +--------------------+---------------------------------------------------------------------------------------------------------------------------+ | ||