namestore.rst (4838B)
1 .. _namestore_rest_api: 2 3 Namestore 4 ========= 5 6 The NAMESTORE REST API. 7 8 Data model 9 ^^^^^^^^^^ 10 11 The following data model definitions are expected to be used in a JSON representation 12 in the respective requests. 13 Responses are provided in the JSON format accordingly. 14 15 .. _RecordSet: 16 .. ts:def:: RecordSet 17 18 interface RecordSet { 19 20 // The name of the record set 21 record_name: string; 22 23 // The record set data array. 24 data: RecordData[]; 25 26 } 27 28 .. _RecordData: 29 .. ts:def:: RecordData 30 31 interface RecordData { 32 33 // The string representation of the record data value, e.g. "1.2.3.4" for an A record 34 value: string; 35 36 // The string representation of the record type, e.g. "A" for an IPv4 address 37 record_type: string; 38 39 // The relative expiration time, in microseconds. Set if is_relative_expiration: true 40 relative_expiration: integer; 41 42 // The absolute expiration time, in microseconds. Set if is_relative_expiration: false 43 absolute_expiration: integer; 44 45 // Whether or not this is a private record 46 is_private: boolean; 47 48 // Whether or not the expiration time is relative (else absolute) 49 is_relative_expiration: boolean; 50 51 // Whether or not this is a supplemental record 52 is_supplemental: boolean; 53 54 // Whether or not this is a shadow record 55 is_shadow: boolean 56 57 // Whether or not this is a maintenance record 58 is_maintenance: boolean 59 } 60 61 .. _NamestoreError: 62 .. ts:def:: GnunetError 63 64 interface GnunetError { 65 66 // The error description 67 error: string; 68 69 // The error code 70 error_code: integer 71 72 } 73 74 75 **NOTE:** All endpoints can return with an HTTP status (5xx). 76 In this case the response body contains a `NamestoreError`_. 77 78 79 Requests 80 ^^^^^^^^ 81 82 .. http:get:: /namestore/$ZNAME 83 84 This endpoint returns all namestore entries for one zone identified by ``$ZNAME``. 85 86 **Request** 87 88 :query record_type: *Optional*. The string representation of a DNS or GNS record type. If given, only record sets including record with this type will be returned. 89 :query omit_private: *Optional*. If set, private records are omitted from the results. 90 :query include_maintenance: *Optional*. If set, maintenance records are included in the results. 91 92 **Response** 93 94 :http:statuscode:`200 Ok`: 95 The body is a `RecordSet`_ array. 96 :http:statuscode:`404 Not found`: 97 The zone was not found. 98 99 .. http:get:: /namestore/$ZNAME/$LABEL 100 101 This endpoint returns the record set under label ``$LABEL`` of the zone 102 identified by ``$ZNAME``. 103 104 **Request** 105 106 :query record_type: *Optional*. The string representation of a DNS or GNS record type. If given, only record sets including record with this type will be returned. 107 :query omit_private: *Optional*. If set, private records are omitted from the results. 108 :query include_maintenance: *Optional*. If set, maintenance records are included in the results. 109 110 **Response** 111 112 :http:statuscode:`200 Ok`: 113 The body is a `RecordSet`_. 114 :http:statuscode:`404 Not found`: 115 The zone or label was not found. 116 117 118 .. http:post:: /namestore/$ZNAME 119 120 Create or append a `RecordSet`_ to a the zone identified by ``$ZNAME``. 121 122 **Request** 123 The request body is a single `RecordSet`_. 124 125 **Response** 126 127 :http:statuscode:`204 No Content`: 128 The zone was successfully added. 129 :http:statuscode:`404 Not found`: 130 The zone was not found. 131 132 .. http:put:: /namestore/$ZNAME 133 134 Create or replace a `RecordSet`_ in the zone identified by ``$ZNAME``. 135 136 **Request** 137 The request body is a single `RecordSet`_. 138 139 **Response** 140 141 :http:statuscode:`204 No Content`: 142 The zone was successfully updated. 143 :http:statuscode:`404 Not found`: 144 The zone was not found. 145 146 147 148 .. http:delete:: /namestore/$ZNAME/$LABEL 149 150 Delete all records under name ``$LABEL`` in the zone identified by ``$ZNAME``. 151 152 **Response** 153 154 :http:statuscode:`204 No Content`: 155 The records were successfully deleted. 156 :http:statuscode:`404 Not found`: 157 The zone or label was not found. 158 159 .. http:post:: /namestore/import/$ZNAME 160 161 Bulk import of record sets into the zone identified by ``$ZNAME``. 162 This API adds the provided array of `RecordSet`_ to the zone. 163 This operation does **NOT** replace existing records under the label(s). 164 If you want a clean import, reset your database before using this API. 165 This API is making sure that the records are added within one database 166 transaction, calling ``GNUNET_NAMESTORE_transaction_begin``, 167 ``GNUNET_NAMESTORE_records_store2`` (successively, if necessary) and finally 168 ``GNUNET_NAMESTORE_transaction_commit``. 169 170 **Request** 171 The request body is a `RecordSet`_ array. 172 173 **Response** 174 175 :http:statuscode:`204 No Content`: 176 The record sets were successfully added. 177 :http:statuscode:`404 Not found`: 178 The zone $ZNAME was not found. 179 180