Namestore
The NAMESTORE REST API.
Data model
The following data model definitions are expected to be used in a JSON representation in the respective requests. Responses are provided in the JSON format accordingly.
interface RecordSet {
// The name of the record set
record_name: string;
// The record set data array.
data: RecordData[];
}
interface RecordData {
// The string representation of the record data value, e.g. "1.2.3.4" for an A record
value: string;
// The string representation of the record type, e.g. "A" for an IPv4 address
record_type: string;
// The relative expiration time, in microseconds. Set if is_relative_expiration: true
relative_expiration: integer;
// The absolute expiration time, in microseconds. Set if is_relative_expiration: false
absolute_expiration: integer;
// Whether or not this is a private record
is_private: boolean;
// Whether or not the expiration time is relative (else absolute)
is_relative_expiration: boolean;
// Whether or not this is a supplemental record
is_supplemental: boolean;
// Whether or not this is a shadow record
is_shadow: boolean
// Whether or not this is a maintenance record
is_maintenance: boolean
}
interface GnunetError {
// The error description
error: string;
// The error code
error_code: integer
}
NOTE: All endpoints can return with an HTTP status (5xx). In this case the response body contains a NamestoreError.
Requests
- GET /namestore/$ZNAME
This endpoint returns all namestore entries for one zone identified by
$ZNAME
.Request
- Query Parameters:
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.
omit_private – Optional. If set, private records are omitted from the results.
include_maintenance – Optional. If set, maintenance records are included in the results.
Response
- 200 Ok:
The body is a RecordSet array.
- 404 Not found:
The zone was not found.
- GET /namestore/$ZNAME/$LABEL
This endpoint returns the record set under label
$LABEL
of the zone identified by$ZNAME
.Request
- Query Parameters:
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.
omit_private – Optional. If set, private records are omitted from the results.
include_maintenance – Optional. If set, maintenance records are included in the results.
Response
- 200 Ok:
The body is a RecordSet.
- 404 Not found:
The zone or label was not found.
- POST /namestore/$ZNAME
Create or append a RecordSet to a the zone identified by
$ZNAME
.- Request
The request body is a single RecordSet.
Response
- 204 No Content:
The zone was successfully added.
- 404 Not found:
The zone was not found.
- PUT /namestore/$ZNAME
Create or replace a RecordSet in the zone identified by
$ZNAME
.- Request
The request body is a single RecordSet.
Response
- 204 No Content:
The zone was successfully updated.
- 404 Not found:
The zone was not found.
- DELETE /namestore/$ZNAME/$LABEL
Delete all records under name
$LABEL
in the zone identified by$ZNAME
.Response
- 204 No Content:
The records were successfully deleted.
- 404 Not found:
The zone or label was not found.
- POST /namestore/import/$ZNAME
Bulk import of record sets into the zone identified by
$ZNAME
. This API adds the provided array of RecordSet to the zone. This operation does NOT replace existing records under the label(s). If you want a clean import, reset your database before using this API. This API is making sure that the records are added within one database transaction, callingGNUNET_NAMESTORE_transaction_begin
,GNUNET_NAMESTORE_records_store2
(successively, if necessary) and finallyGNUNET_NAMESTORE_transaction_commit
.- Request
The request body is a RecordSet array.
Response
- 204 No Content:
The record sets were successfully added.
- 404 Not found:
The zone $ZNAME was not found.