.. _ref-type:

GNS API Service
===============

Definition
~~~~~~~~~~

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

``lookup`` is the combination of the ``record_name`` of a :ref:`ref-gnsrecord` and the ``name`` of the zone (or identity): ``record_name.name``

``type`` is the record_type of a :ref:`ref-gnsrecord`.

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)  Record not found            - GNS record was not found, this is combined with the HTTP Error Code 404 Not Found

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

Requests
~~~~~~~~

GET Request
-----------

For this request ``record_type`` is optional. If missing or called with an invalid record_type, it will automatically be set to ANY.

The success response is a :ref:`ref-gnsrecord` without its record_name.

+--------------------+----------------------------------------------------------------------------------------------------------------------------+
|**Title**           |Return all records for given name                                                                                           |
+--------------------+----------------------------------------------------------------------------------------------------------------------------+
|**URL**             |:literal:`/gns/'lookup'?record_type='type'`                                                                                 |
+--------------------+----------------------------------------------------------------------------------------------------------------------------+
|**Method**          |**GET**                                                                                                                     |
+--------------------+----------------------------------------------------------------------------------------------------------------------------+
|**Data Params**     |none                                                                                                                        |
+--------------------+----------------------------------------------------------------------------------------------------------------------------+
|**Success Response**| [{"value": "*value*", "record_type": "*type*", "expiration_time": "*time*", "flag": *flag*},...]                           |
+--------------------+----------------------------------------------------------------------------------------------------------------------------+
|**Error Response**  | {"error":"*error_desc*"} :sup:`2`                                                                                          |
+--------------------+----------------------------------------------------------------------------------------------------------------------------+

OPTIONS Request
---------------

+--------------------+----------------------------------------------------------------------------------------------------------------------------+
|**Title**           |Get request options                                                                                                         |
+--------------------+----------------------------------------------------------------------------------------------------------------------------+
|**URL**             |:literal:`/gns`                                                                                                             |
+--------------------+----------------------------------------------------------------------------------------------------------------------------+
|**Method**          |**OPTIONS**                                                                                                                 |
+--------------------+----------------------------------------------------------------------------------------------------------------------------+
|**URL Params**      |none                                                                                                                        |
+--------------------+----------------------------------------------------------------------------------------------------------------------------+
|**Data Params**     |none                                                                                                                        |
+--------------------+----------------------------------------------------------------------------------------------------------------------------+
|**Success Response**|                                                                                                                            |
+--------------------+----------------------------------------------------------------------------------------------------------------------------+
|**Error Response**  |none                                                                                                                        |
+--------------------+----------------------------------------------------------------------------------------------------------------------------+
