commit 8ce1befc020379ffb8feee1a5686a697c77935a5
parent bc6bbd4031ee382c3013a811f6d4f3a30da27c37
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Tue, 18 Oct 2022 14:11:51 +0900
minor
Diffstat:
1 file changed, 27 insertions(+), 23 deletions(-)
diff --git a/developers/rest/namestore.rst b/developers/rest/namestore.rst
@@ -3,10 +3,14 @@
Namestore
=========
-Record Set
+The NAMESTORE REST API.
+
+Data model
^^^^^^^^^^
-Namestore entries are GNS record sets. A record set consists of a ``record_name`` and a ``data`` field.
+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.
.. _RecordSet:
.. ts:def:: RecordSet
@@ -49,39 +53,39 @@ Namestore entries are GNS record sets. A record set consists of a ``record_name`
}
-Error Response
-^^^^^^^^^^^^^^
+.. _NamestoreError:
+.. ts:def:: NamestoreError
-All error responses are sent with a `NamestoreError`_ body.
+ interface NamestoreError {
- .. _NamestoreError:
- .. ts:def:: NamestoreError
+ // The error description
+ error: string;
- interface NamestoreError {
+ }
- // The error description
- error: string;
- }
+**NOTE:** All endpoints can return with an HTTP status (5xx).
+In this case the response body contains a `NamestoreError`_.
+
Requests
^^^^^^^^
.. http:get:: /namestore/$ZNAME
- This endpoint returns all namestore entries for one zone identified by $NAME.
+ This endpoint returns all namestore entries for one zone identified by ``$ZNAME``.
**Response**
:http:statuscode:`200 Ok`:
The body is a `RecordSet`_ array.
:http:statuscode:`404 Not found`:
- The zone $ZNAME was not found.
+ The zone was not found.
.. http:post:: /namestore/$ZNAME
- Create or append a record set under a label.
+ Create or append a `RecordSet`_ to a the zone identified by ``$ZNAME``.
**Request**
The request body is a single `RecordSet`_.
@@ -89,13 +93,13 @@ Requests
**Response**
:http:statuscode:`204 No Content`:
- The record set was successfully added.
+ The zone was successfully added.
:http:statuscode:`404 Not found`:
- The zone $ZNAME was not found.
+ The zone was not found.
.. http:put:: /namestore/$ZNAME
- Create or replace a record set under a label.
+ Create or replace a `RecordSet`_ in the zone identified by ``$ZNAME``.
**Request**
The request body is a single `RecordSet`_.
@@ -103,26 +107,26 @@ Requests
**Response**
:http:statuscode:`204 No Content`:
- The record set was successfully updated.
+ The zone was successfully updated.
:http:statuscode:`404 Not found`:
- The zone $ZNAME was not found.
+ The zone was not found.
.. http:delete:: /namestore/$ZNAME?record_name=$RNAME
- Delete the record set under name $RNAME in zone $ZNAME
+ Delete all records under name ``$RNAME`` in the zone identified by ``$ZNAME``.
**Response**
:http:statuscode:`204 No Content`:
- The record set under $RNAME was successfully deleted.
+ The records were successfully deleted.
:http:statuscode:`404 Not found`:
- The zone $ZNAME was not found.
+ The zone was not found.
.. http:post:: /namestore/import/$ZNAME
- Bulk import of record sets into a zone.
+ 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.
