Getting Started
===============

The Narravero API is a REST interface that provides an interface for creating and updating Tridys.

A low-level documentation can be found here: `OpenAPI Documentation </v1/api-docs>`_.

A DPP is generated for every :term:`Tridy` in Narravero. The layout and design of a DPP is defined by a :term:`DPP Template` and a Tridy is described by a :term:`Content Type`.

For our first generated DPP, we need the following parts:

* Data that represents our product
* DPP Template and Content Type
* Interface to receive Data
* Our first Tridy via the API

Data
^^^^

The data we receive for Tridys is freely structured JSON. The only cases where the structure matters is 
when accessing the data from a DPP Template or if the JSON contains identifiers or media Narravero should process.

.. code-block:: JSON

   {
     "ean": "12345678",
     "productName": "White, fancy Sneaker",
     "price": "123,32€"
   }

This data will be used throughout this tutorial.

DPP Template and Content Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A DPP Template defines the design and layout of a DPP. It is filled with data from a Tridy via placeholders. 
A Content Type describes the content of a Tridy and is the link to the DPP Template.

.. image:: images/publisher-templates.png

A new empty DPP Template can be created with a name describing it:

.. image:: images/publisher-new-template.png

A DPP Template consists of so called Widgets, that represent the contents of the DPP. 

We start by adding a Text Widget to the DPP by clicking "Add element", pick "Text", and then edit it by clicking on it:

.. image:: images/publisher-edit-text.png

We used a placeholder here: ``${productName}`` that will be replaced by the data in the Tridy ("White,fancy Sneaker").

After "Apply"ing the changes, we use "Publish Design" to store all changes.

Creating a DPP Template also creates a Content Type of the same name.


Interface
^^^^^^^^^

The interface is defined via the user context menu in the upper right corner of the DPP Publisher. It has a unique name that is used to access it via the API:

.. image:: images/publisher-interfaces.png

Make sure you give your Interface a name that is recognizable:

.. image:: images/publisher-interface-new.png

Please note we need to select "ID" for "Content Type" and then pick our content type we created earlier.


Create first Tridy
^^^^^^^^^^^^^^^^^^

Now we finally reach the API level of the tutorial and we create our first Tridy using the API.

To give the API a try, we can do this right from the `OpenAPI documentation </v1/api-docs>`_.

First we need to authenticate to the Narravero API using the Narravero API token we received.

We can do that on the `Authentication </v1/api-docs#auth>`_ page:

.. image:: images/openapi-authenticate.png

After clicking "Set", we are all set to create our first Tridy in `Create Tridy </v1/api-docs#post-/v1/tridy/-interfaceName->`_:

We set the name of our Interface and provide the sample data:

.. image:: images/openapi-create-tridy.png

After clicking "Try", we can see the result below:

.. image:: images/openapi-create-tridy-result.png

Since we didn't yet define any ``ids`` in the Interface, the list of ids is empty. 

We received our first Tridy-ID ``17vSd3yT6Gcg82dwKxg4NY`` and also the URL 
for our first DPP: ``https://nvero.app/17vSd3yT6Gcg82dwKxg4NY`` that we can `open <https://nvero.app/17vSd3yT6Gcg82dwKxg4NY>`_: