Namestore API Service — GNUnet documentation

# Namestore API Service

## Definition

Variables in single quotes `'...'` can or must be changed according to your specific case.

`name` is the name of a zone. A zone is the name of an identity in this case.

### GNS Record

Namestore entries are GNS records. GNS records have a `record_type`, a `value`, an `expiration_time`, a `flag` and a `record_name`. Adding a GNS records with the same record_name overwrites the old GNS record.

A GNS record is sent in the JSON format: `{"value": "value", "record_type": "type", "expiration_time": "time", "flag": flag, "record_name": "rname"}`

`type` is the type of the record, e.g. "PKEY" for private key. It can be ANY, PKEY, NICK, LEHO, VPN, GNS2DNS, BOX, PLACE, PHONE, ID_ATTR, ID_TOKEN, ID_TOKEN_METADATA, CREDENTIAL, POLICY, ATTRIBUTE, ABE_KEY, ABE_MASTER. You can find more information in header `src/gnunet_gnsrecord_lib.h`

`value` is the value of the specific type of the record, e.g. the private key of an identity.

`time` is the expiration time of the record either "never" or fancy time (see GNUNET_STRINGS_fancy_time_to_absolute)

`flag` is the option of the record. Either 0 for none, 2 for private, 8 for relative expiration or 16 if all other records have expired. `flag` must be a number.

`rname` is the name of the record.

### Error Response

An error response is sent in the JSON format: `{"error":"*error_description*"}`

Following numbers are added for references inside the documentation only.

Error descriptions are:

    Nr. Error Description           - Explanation
    1)  Unknown Error               - Error is not specified
    2)  No identity found           - Identity was not found with given name, this is combined with the HTTP Error Code 404 Not Found
    3)  No default zone specified   - Identity name was not given and no identiy was added to the subsystem namestore
    4)  Namestore action failed     - The task of the namestore API (not REST API) failed
    5)  No data                     - Missing data
    6)  Data invalid                - Wrong data given
    7)  Error storing records       - POST request failed
    8)  Deleting record failed      - DELETE request failed
    9)  No record found             - Delete failed due to missing record, this is combined with the HTTP Error Code 404 Not Found

Error `1)` is always possible and is not listed in following requests.

ATTENTION: Any error message from the Namestore API (not REST API) can occur and can be returned in the error response. These responses are not listed here.

## Requests

### GET Request

Title | Returns all namestore entries of default identity
URL | `/namestore`
Method | GET
URL Params | none
Data Params | none
Success Response | [{"value": "value", "record_type": "type", "expiration_time": "time", "flag": flag, "record_name": "rname"},...]
Error Response | {"error":"error_desc"} 3; 4

Title | Returns all namestore entries for one zone specified by its name
URL | `/namestore/'name'`
Method | GET
URL Params | none
Data Params | none
Success Response | [{"value": "value", "record_type": "type", "expiration_time": "time", "flag": flag, "record_name": "rname"},...]
Error Response | {"error":"error_desc"} 2; 4

### POST Request

Title | Creates a namestore entry for default identity
URL | `/namestore`
Method | POST
URL Params | none
Data Params | {"value": "value", "record_type": "type", "expiration_time": "time", "flag": flag, "record_name": "rname"}
Success Response | Response Code: `204` (No Content)
Error Response | {"error":"error_desc"} 3; 4; 5; 6; 7

Title | Creates a namestore entry for one zone specified by its name
URL | `/namestore/'name'`
Method | POST
URL Params | none
Data Params | {"value": "value", "record_type": "type", "expiration_time": "time", "flag": flag, "record_name": "rname"}
Success Response | Response Code: `204` (No Content)
Error Response | {"error":"error_desc"} 2; 4; 5; 6; 7

### DELETE Request

Title | Deletes specific namestore entry for default identity
URL | `/namestore?record_name='rname'`
Method | DELETE
URL Params | none
Data Params | none
Success Response | Response Code: `204` (No Content)
Error Response | {"error":"error_desc"} 3; 4; 6; 8; 9

Title | Deletes specific namestore entry in specific zone
URL | `/namestore/'name'?record_name='rname'`
Method | DELETE
URL Params | none
Data Params | none
Success Response | Response Code: `204` (No Content)
Error Response | {"error":"error_desc"} 2; 4; 6; 8; 9

### OPTIONS Request

Title | Gets request options
URL | `/namestore`
Method | OPTIONS
URL Params | none
Data Params | none
Success Response |
Error Response | none