Skip to main content
`Ctrl`+`K`

# 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

    }

    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, calling `GNUNET_NAMESTORE_transaction_begin`, `GNUNET_NAMESTORE_records_store2` (successively, if necessary) and finally `GNUNET_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.