name-server-protocol.md (5688B)
1 # Name Server Protocol 2 3 The protocol used by Jami to query and register a name is based on an 4 HTTP 5 [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) 6 API answering requests with JSON documents and regular HTTP status 7 codes. 8 9 The public nameserver is hosted at `ns.jami.net` and uses a blockchain as 10 its backend. Another implementation could use any other database or 11 directory service making the nameserver protocol reusable. 12 13 ## Rules on name formatting 14 15 Usernames are checked by a regex to ensure some rules about their 16 format: 17 18 - Length must be between 3 and 32 characters 19 - Those characters must be alphanumerical with underscore `_` being 20 also accepted. 21 22 ## Querying a name 23 24 This is the main service provided by a name server. It enables to get 25 the RingID corresponding to a username. 26 27 ### Request 28 29 A request for the name `foobar` is a `GET` request with 30 `/name/`*`foobar`* as the URI. 31 32 ### Response (Success) 33 34 If the name is found, a response with status code `200` `OK` must be 35 sent to the client with a `Content-type` field set as 36 `application/json`. 37 38 The body is a JSON documents with 2 string attributes : `name` and 39 `addr`. `name` is equal to the one requested and `addr` is an 40 hexadecimal representation of the RingID prefixed with `0x`. 41 42 In our example, the JSON answer would be: 43 44 ```javascript 45 { 46 "name":"foobar", 47 "addr":"0x29347542eb07159f316577e1ae16243d152f6b7b" 48 } 49 ``` 50 51 ### Response (Not found) 52 53 If the name is not found, a response with status code `404` `Not` 54 `Found` must be sent to the client with a `Content-type` field set as 55 `application/json`. 56 57 The body is a JSON documents with 1 string attribute : `error`. This 58 attribute is filled with an error message that explains the error (and 59 could be displayed in the client in the future). 60 61 On the reference implementation, the returned document is: 62 63 ```javascript 64 { 65 "error":"name not registred" 66 } 67 ``` 68 69 Querying an address 70 ------------------- 71 72 This service is a reverse lookup. You query for an address and a 73 username is returned if one is registered on the name server. 74 75 ### Request 76 77 A request for the ID `ring:29347542eb07159f316577e1ae16243d152f6b7b` 78 is a `GET` request with 79 `/addr/`*`29347542eb07159f316577e1ae16243d152f6b7b`* as the URI. 80 81 ### Response (Success) 82 83 If the address corresponds to a username, a response with status code 84 `200` `OK` must be sent to the client with a `Content-type` field set as 85 `application/json`. 86 87 The body is a JSON documents with 1 string attribute : `name`. The value 88 of this field is the name registered to this address 89 90 In our example, the JSON answer would be: 91 92 ```javascript 93 { 94 "name":"foobar" 95 } 96 ``` 97 98 ### Response (Not found) 99 100 If the address is not found, a response with status code `404` `Not` 101 `Found` must be sent to the client with a `Content-type` field set as 102 `application/json`. 103 104 The body is a JSON documents with 1 string attribute : `error`. This 105 attribute is filled with an error message that explains the error (and 106 could be displayed in the client in the future). 107 108 On the reference implementation, the returned document is: 109 110 ```javascript 111 { 112 "error":"address not registred" 113 } 114 ``` 115 116 Registering a name 117 ------------------ 118 119 This part of the protocol is used to register a new name/address pair. 120 It is used on the main public registry but may be optional in a custom 121 implementation. 122 123 ### Request 124 125 A request for registering the name `foobar` is a `POST` request with 126 `/name/`*`foobar`* as the URI. The header attribute `Content-type` must 127 be set to `application/json`. 128 129 The body of the request is a JSON document with 2 string attributes: 130 `addr` and `owner`. `addr` contains the RingID prefixed with `0x` and 131 `owner` is the name to be registered. 132 133 An example for `foobar` could be: 134 135 ```javascript 136 { 137 "addr":"0x29347542eb07159f316577e1ae16243d152f6b7b", 138 "owner":"foobar" 139 } 140 ``` 141 142 ### Response (Success) 143 144 If the name/address pair is successfully registered, a response with 145 status code `200` `OK` must be sent to the client with a `Content-type` 146 field set as `application/json`. 147 148 The body contain a JSON document with 1 boolean attribute `success` set 149 to `true`. 150 151 As an example: 152 153 ```javascript 154 { 155 "success":true 156 } 157 ``` 158 159 Further attempts to query the name or the address should then be 160 successful. 161 162 ### Response (Bad request) 163 164 If the registration cannot be achieved because of an error in the 165 request (formatting, missing attribute, etc.), a response with status 166 code `400` `Bad` `Request` must be sent to the client with a 167 `Content-type` field set as `application/json`. 168 169 The body is a JSON documents with 2 attributes: `success` which is a 170 boolean and `error` which is a string. `success` is set to `false` and 171 `error` is filled with an error message that explains the error (and 172 could be displayed in the client in the future). 173 174 For an invalid formatting of the username, the body could be: 175 176 ```javascript 177 { 178 "success": false, 179 "error": "invalid name" 180 } 181 ``` 182 183 ### Response (Forbidden) 184 185 If the registration cannot be achieved because the name is already 186 taken, a response with status code `403` `Forbidden` must be sent to the 187 client with a `Content-type` field set as `application/json`. 188 189 The body is a JSON documents with 3 attributes: `success` which is a 190 boolean set to `false`, `name` and `addr` which are both strings 191 replicated from the original request. 192 193 Registering `foobar`, with it being already registered, would lead to 194 the following response: 195 196 ```javascript 197 { 198 "success": false, 199 "name":"foobar", 200 "addr":"0x29347542eb07159fdeadbeefae16243d152f6b7b" 201 } 202 ``` 203 204 ## Some links 205 206 - [ring-nameservice](https://github.com/savoirfairelinux/ring-nameservice): 207 reference NodeJS implementation used by `ns.ring.cx` and querying an 208 Ethereum node.