.. include:: /Includes.rst.txt
.. _rest-transactions:

============
Transactions
============

.. toctree::
   :hidden:
   :glob:
   

There are two kind of queries that you need to know of.

1. Queries with a transaction
=============================

Most of our queries need a **transaction** to be started on our server side in advance. This is something you have to initiate and control yourself.
You will know that you need to start a (or have a running) transaction if you see `trx=` in a request URL.

Transaction begin
-----------------

To start a transaction you have to call  

.. code:: console

   transaction/begin

This will return a json object with an `id`

.. code:: js

    {
        id: string
    } 


This id is used as the `trx` GET param in queries that need to be executed in a transaction.

Transaction usage
-----------------

.. code:: console

   variable/get/trx=[HERE COMES THE TRX ID]&id=123

So whenever you see a query that has a `trx` param, be sure to have an open transaction.


.. note::
   You can run multiple queries within one transaction, as long as it hasn't been closed.
   
Transcation commit
------------------

Commit your changes on configuration database. Without commit all changes will be reverted on transaction close

.. code:: console

   transaction/commit_sync/trx=[TRX_ID]
   
Transcation rollback
--------------------

Rollback your configuration changes on error

.. code:: console

   transaction/rollback/trx=[TRX_ID]

Transaction close
-----------------

But remember that each transaction that you have started needs to be closed again.

.. code:: console

   transaction/close/trx=[TRX_ID]

.. warning::
   You must close each transaction after your fetch is completed. There is only a limitted amount of open transactions allowed. If you open the maximum amount you have to wait for a transaction-timeout to have a new transaction slot become available.

2. Queries without any transaction
==================================

There are also some queries, like the authentication and requests for configs that are used without any transaction id.

You can execute them while within a transaction or outside of a transaction context. It does not matter.