identity.rst (13540B)
1 Identity 2 ======== 3 4 Definition 5 ~~~~~~~~~~ 6 7 Variables in single quotes ``'...'`` can or must be changed according to your specific case. 8 9 ``public_key`` is the public key of an identity. 10 11 ``name`` is the name of an identity. 12 13 ``newname`` is the new name of an identity for the rename request. 14 15 ``subsystem`` is a subsystem, e.g. namestore. 16 17 Identity 18 -------- 19 20 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. 21 22 23 Error Response 24 -------------- 25 26 An error response is sent in the JSON format: ``{"error":"*error_description*"}`` 27 28 Following numbers are added for references inside the documentation only. 29 30 Error descriptions are:: 31 32 Nr. Error Description - Explanation 33 1) Unknown Error - Error is not specified 34 2) No identity found - Identity was not found with given name, public key or no identity was found at all 35 3) Missing identity public key - Identity public key length is zero 36 4) Missing identity name - Identity name length is zero 37 5) Missing subsystem name - Subsystem name length is zero 38 6) No data - No JSON data given 39 7) Data invalid - Wrong JSON data given 40 8) Rename failed - Rename request failed due to wrong name, etc. 41 9) Setting subsystem failed - Setting the subsystem for an identity failed (usually this error does not occur) 42 43 Error ``1)`` is always possible and is not listed in following requests. 44 45 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. 46 47 Response Code 48 ------------- 49 50 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:: 51 52 a) 200 OK - Normal response (but may contain an error message) 53 b) 201 Created - Success after POST request 54 c) 204 No Content - Success PUT or DELETE request 55 d) 404 Not Found - Identity is not found with identifier 56 e) 409 Conflict - PUT or POST request not possible due to existing duplicate 57 58 ``d) 404 Not Found`` is always used when the error message is either ``2)``, ``3)`` or ``4)``. 59 60 Requests 61 ~~~~~~~~ 62 63 GET Requests 64 ------------ 65 66 +--------------------+---------------------------------------------------------------+ 67 |**Title** |Returns all identities with name and public key | 68 +--------------------+---------------------------------------------------------------+ 69 |**URL** |:literal:`/identity/all` | 70 +--------------------+---------------------------------------------------------------+ 71 |**Method** |**GET** | 72 +--------------------+---------------------------------------------------------------+ 73 |**URL Params** |none | 74 +--------------------+---------------------------------------------------------------+ 75 |**Data Params** |none | 76 +--------------------+---------------------------------------------------------------+ 77 |**Success Response**|[{"pubkey":"*public_key*", "name":"*name*"},...] | 78 +--------------------+---------------------------------------------------------------+ 79 |**Error Response** | {"error":"*error_desc*"} :sup:`2` | 80 +--------------------+---------------------------------------------------------------+ 81 |**Attention** | The response in this request is an array! | 82 +--------------------+---------------------------------------------------------------+ 83 84 | 85 86 +--------------------+----------------------------------------------------------------+ 87 |**Title** |Returns only a specific identity | 88 +--------------------+----------------------------------------------------------------+ 89 |**URL** | ``/identity/pubkey/'public_key'`` or ``/identity/name/'name'`` | 90 +--------------------+----------------------------------------------------------------+ 91 |**Method** |**GET** | 92 +--------------------+----------------------------------------------------------------+ 93 |**URL Params** |none | 94 +--------------------+----------------------------------------------------------------+ 95 |**Data Params** |none | 96 +--------------------+----------------------------------------------------------------+ 97 |**Success Response**|{"pubkey":"*public_key*", "name":"*name*"} | 98 +--------------------+----------------------------------------------------------------+ 99 |**Error Response** | {"error":"*error_desc*"} :sup:`2; 3 or 4` | 100 +--------------------+----------------------------------------------------------------+ 101 102 | 103 104 +--------------------+---------------------------------------------------------------+ 105 |**Title** |Returns default identity for specific subsystem | 106 +--------------------+---------------------------------------------------------------+ 107 |**URL** |:literal:`/identity/subsystem/'subsystem'` | 108 +--------------------+---------------------------------------------------------------+ 109 |**Method** |**GET** | 110 +--------------------+---------------------------------------------------------------+ 111 |**URL Params** |none | 112 +--------------------+---------------------------------------------------------------+ 113 |**Data Params** |none | 114 +--------------------+---------------------------------------------------------------+ 115 |**Success Response**|{"pubkey":"*public_key*", "name":"*name*"} | 116 +--------------------+---------------------------------------------------------------+ 117 |**Error Response** | {"error":"*error_desc*"} :sup:`2; 5` | 118 +--------------------+---------------------------------------------------------------+ 119 120 POST Request 121 ------------ 122 123 +--------------------+---------------------------------------------------------------+ 124 |**Title** |Creates an identity | 125 +--------------------+---------------------------------------------------------------+ 126 |**URL** |:literal:`/identity` | 127 +--------------------+---------------------------------------------------------------+ 128 |**Method** |**POST** | 129 +--------------------+---------------------------------------------------------------+ 130 |**URL Params** |none | 131 +--------------------+---------------------------------------------------------------+ 132 |**Data Params** | {"name":'*name*'} | 133 +--------------------+---------------------------------------------------------------+ 134 |**Success Response**| Response Code: :literal:` b) 201 Created` | 135 +--------------------+---------------------------------------------------------------+ 136 |**Error Response** | | {"error":"*error_desc*"} :sup:`6; 7` | 137 | | | *or* | 138 | | | Response Code: ``e) 409 Conflict`` if name in use | 139 +--------------------+---------------------------------------------------------------+ 140 141 PUT Request 142 ----------- 143 144 +--------------------+----------------------------------------------------------------+ 145 |**Title** |Changes name of identity | 146 +--------------------+----------------------------------------------------------------+ 147 |**URL** | ``/identity/pubkey/'public_key'`` or ``/identity/name/'name'`` | 148 +--------------------+----------------------------------------------------------------+ 149 |**Method** |**PUT** | 150 +--------------------+----------------------------------------------------------------+ 151 |**URL Params** |none | 152 +--------------------+----------------------------------------------------------------+ 153 |**Data Params** | {"newname":'*newname*'} | 154 +--------------------+----------------------------------------------------------------+ 155 |**Success Response**| Response Code: :literal:`c) 204 No Content` | 156 +--------------------+----------------------------------------------------------------+ 157 |**Error Response** | | {"error":"*error_desc*"} :sup:`2; 3 or 4; 6; 7; 8` | 158 | | | *or* | 159 | | | Response Code: :literal:`e) 409 Conflict` if newname in use | 160 +--------------------+----------------------------------------------------------------+ 161 162 | 163 164 +--------------------+----------------------------------------------------------------+ 165 |**Title** |Sets identity as default for a subsystem | 166 +--------------------+----------------------------------------------------------------+ 167 |**URL** | ``/identity/subsystem/'name'`` | 168 +--------------------+----------------------------------------------------------------+ 169 |**Method** |**PUT** | 170 +--------------------+----------------------------------------------------------------+ 171 |**URL Params** |none | 172 +--------------------+----------------------------------------------------------------+ 173 |**Data Params** | {"subsystem":'*subsystem*'} | 174 +--------------------+----------------------------------------------------------------+ 175 |**Success Response**| Response Code: :literal:`c) 204 No Content` | 176 +--------------------+----------------------------------------------------------------+ 177 |**Error Response** | {"error":"*error_desc*"} :sup:`2; 4; 6; 7; 9` | 178 +--------------------+----------------------------------------------------------------+ 179 180 DELETE Request 181 -------------- 182 183 +--------------------+----------------------------------------------------------------+ 184 |**Title** |Deletes specific identity | 185 +--------------------+----------------------------------------------------------------+ 186 |**URL** | ``/identity/pubkey/'public_key'`` or ``/identity/name/'name'`` | 187 +--------------------+----------------------------------------------------------------+ 188 |**Method** |**DELETE** | 189 +--------------------+----------------------------------------------------------------+ 190 |**URL Params** |none | 191 +--------------------+----------------------------------------------------------------+ 192 |**Data Params** |none | 193 +--------------------+----------------------------------------------------------------+ 194 |**Success Response**| Response Code: :literal:`c) 204 No Content` | 195 +--------------------+----------------------------------------------------------------+ 196 |**Error Response** | {"error":"*error_desc*"} :sup:`2; 3 or 4` | 197 +--------------------+----------------------------------------------------------------+ 198 199 OPTIONS Request 200 --------------- 201 202 +--------------------+----------------------------------------------------------------+ 203 |**Title** |Gets request options | 204 +--------------------+----------------------------------------------------------------+ 205 |**URL** |:literal:`/identity` | 206 +--------------------+----------------------------------------------------------------+ 207 |**Method** |**OPTIONS** | 208 +--------------------+----------------------------------------------------------------+ 209 |**URL Params** |none | 210 +--------------------+----------------------------------------------------------------+ 211 |**Data Params** |none | 212 +--------------------+----------------------------------------------------------------+ 213 |**Success Response**| | 214 +--------------------+----------------------------------------------------------------+ 215 |**Error Response** |none | 216 +--------------------+----------------------------------------------------------------+