.. target audience: developer, core developer

.. _sandbox-api:

Current Sandbox API
###################

..
  Current Sandbox endpoints.

  GET /
  Welcome message.

  ** Camt debug **

  POST /admin/payments/camt 
  give last statement of requesting account

  ** Bank accounting **

  POST /admin/bank-accounts/$accountLabel 
  create bank account (no EBICS involved)

  GET /admin/bank-accounts
  Give summary of all the bank accounts.

  GET /admin/bank-accounts/$accountLabel 
  give general information about a bank account

  ** Transactions **

  POST /admin/bank-accounts/$accountLabel/simulate-incoming-transaction
  Book one incoming transaction for $accountLabel.
  The debtor (not required to be in the same bank)
  information is taken from the request.

  GET /admin/bank-accounts/$accountLabel/transactions
  Inform about all the transactions of one bank account.

  POST /admin/bank-accounts/$accountLabel/generate-transactions
  Generate one incoming and one outgoing transaction
  for one bank account.

  ** EBICS subscribers management **

  POST /admin/ebics/subscribers
  Create a new EBICS subscriber.

  GET /admin/ebics/subscribers
  Give details of all the EBICS subscribers in the bank.

  POST /admin/ebics/bank-accounts
  Create a *new* bank account and link it with a existing
  EBICS subscriber.

  ** EBICS host management **

  POST /admin/ebics/hosts/$hostID/rotate-keys
  Change the bank's keys used in EBICS communication.

  POST /admin/ebics/hosts
  Create a new EBICS host.

  GET /admin/ebics/hosts
  Show details of all the EBICS hosts in the bank. 

  ** EBICS serving **

  POST /ebicsweb
  Processes a EBICS request.

  ** Taler .. **

  GET /taler
  Show one taler://-URI to initiate a withdrawal.

  - Taler integration API.

  - Demobank configuration API.
    ToDo.

  - Taler access API.
    ToDo.

EBICS.
^^^^^^

Hosts.
++++++

.. http:post:: /admin/ebics/hosts

   Creates a new Ebics host.

   **Request:**

    .. ts:def:: EbicsHostRequest

     interface EbicsHostRequest {

       // Ebics version.
       hostID: string;

       // Name of the host.
       ebicsVersion: string;
     }


.. http:get:: /admin/ebics/hosts

   Shows the list of all the hosts in the system.

   **Response:**

    .. ts:def:: EbicsHostResponse

     interface EbicsHostResponse {

       // shows the host IDs that are active in the system.
       // The Ebics version *is* missing, but it's still available
       // via the HEV message.
       ebicsHosts: string[];
     }

.. http:post:: /admin/ebics/hosts/$hostID/rotate-keys

   Overwrite the bank's Ebics keys with random ones.  This is entirely
   meant for tests (as the Sandbox itself is) and no backup will be
   produced along this operation.


Subscribers.
++++++++++++

.. http:post:: /admin/ebics/bank-accounts

  Associates a new bank account to an existing subscriber.

  **Request:**

    .. ts:def:: BankAccountRequest

     interface BankAccountRequest {

       // Ebics subscriber
       subscriber: string;

       // IBAN
       iban: string;

       // BIC
       bic: string;

       // human name
       name: string;

       // bank account label
       label: string;

     }


.. http:post:: /admin/ebics/subscribers

   Creates a new Ebics subscriber.

   **Request:**

   .. ts:def:: SubscriberRequest

     interface SubscriberRequest {

       // hostID
       hostID: string;

       // userID
       userID: string;

       // partnerID
       partnerID: string;

       // systemID
       systemID: string;

     }


.. http:get:: /admin/ebics/subscribers

   Shows the list of all the subscribers in the system.

   **Response:**

    .. ts:def:: SubscribersResponse

     interface SubscribersResponse {

       subscribers: Subscriber[]
     }

    .. ts:def:: Subscriber

      interface Subscriber {

        // userID
        userID: string;

        // partnerID
        partnerID: string;

        // hostID
        hostID: string;

      }


Bank accounts.
^^^^^^^^^^^^^^

.. http:get:: /admin/bank-accounts

   Give summary of all the bank accounts.

.. http:get:: /admin/bank-accounts/$accountLabel

   Give information about a bank account.


Main EBICS service.
^^^^^^^^^^^^^^^^^^^

.. http:post:: /ebicsweb

   Serves all the Ebics requests.


Transactions.
^^^^^^^^^^^^^

JSON.
+++++

.. http:get:: /admin/bank-accounts/$accountLabel/transactions

   Inform about all the transactions of one bank account.

.. http:post:: /admin/bank-accounts/$accountLabel/generate-transactions

   Generate one incoming and one outgoing transaction for one bank account.

.. http:post:: /admin/bank-accounts/$accountLabel/simulate-incoming-transaction

   Book one incoming transaction for $accountLabel.
   The debtor (not required to be in the same bank)
   information is taken from the request.


Camt.
+++++

.. http:post:: /admin/payments/camt

  Return the last statement of the requesting account.

  **Request**

   .. code-block:: tsref

     interface CamtParams {

       // label of the bank account being queried.
       bankaccount: string;

       // The Camt type to return.  Only '53' is allowed
       // at this moment.
       type: number;
     }

  **Response**

  The expected Camt.053 document.

Future Sandbox API
##################

Resources.
----------

Sandbox serves the following resources:

 - Demobanks.
 - Bank accounts.
 - Subscribers.
 - Transactions.
 - Customers.
 - Reports.
 
The resources are subject to all CRUD operations, via by two
types of users: the 'admin' and the customers.  The admin has
rights on all of them.

One of the main differences with the previous versions is the
removal of the "/admin" initial component.  If the administrator
authenticates for one operation, then this one is of type `admin`:
no need for a dedicate and extra URI part.

For example, mocking transactions in the system was a typical
/admin-operation, but since transactions themselves are resources
and any resource is subject to CRUD operations, then mocking one
becomes just a `C` operation on the 'transactions' resources.  If
a test case wants to simplify the authentication - by hard-coding
the credentials, for example - before mocking one transaction, then
it can impersonate the administrator.

.. note::

   ``POST``-ing to a endpoint with a trailing ``$id`` means
   modification of a existing resource.

Demobanks
^^^^^^^^^

Demobanks are the main containers of all the other resources.
They take configuration values, like the currency for example.

.. http:get:: /admin/demobanks
.. http:get:: /admin/demobanks/$id
.. http:post:: /admin/demobanks
.. http:post:: /admin/demobanks/$id
.. http:delete:: /admin/demobanks/$id

Bank accounts.
^^^^^^^^^^^^^^

Bank accounts collect money of customers and participate
in transactions.

The ``$base`` is one demobank, in the form ``/demobanks/$id``.
That is due because a bank account must inherit some defaults
from the demobank, like the currency.

.. http:get:: $base/bankaccounts
.. http:get:: $base/bankaccounts/$id
.. http:post:: $base/bankaccounts
.. http:post:: $base/bankaccounts/$id
.. http:delete:: $base/bankaccounts/$id

Subscribers.
^^^^^^^^^^^^

Subscribers are (optional) customers identities for protocols
other than the native one.

A subscriber is not required to have a bank account `soon`.  Therefore,
it can be created, and later be linked to one bank account.  For this
reason, the ``$base`` should not mention one bank account.

.. note::

   Creating a subscriber is a time-consuming operation that goes often
   through slow channels, therefore it should basically never be done
   more than once.

.. http:get:: $base/subscribers
.. http:get:: $base/subscribers/$id
.. http:post:: $base/subscribers
.. http:post:: $base/subscribers/$id
.. http:delete:: $base/subscribers/$id

Transactions.
^^^^^^^^^^^^^

Transactions are money movements between bank accounts.

For convenience, ``$base`` **could** mention one bank account
to let customers see their transactions without defining "history"
query parameters: like ``$demobank/bankaccounts/$bankaccountId/transactions``.

At the same time, transactions should be easy to query regardless
of whose bank account they involve -- for administrative reasons, for
example.  Hence, a "global" URI scheme like ``$demobank/transactions?param=XXX``
should be offered as well.

.. http:get:: $base/transactions
.. http:get:: $base/transactions/$id
.. http:post:: $base/transactions
.. http:post:: $base/transactions/$id
.. http:delete:: $base/transactions/$id

Customers.
^^^^^^^^^^

Customers are persons that **can** have one bank account.  As
with subscribers, ``$base`` should not mention any bank account
so as to leave more flexibility to assign new bank accounts to
the same customer.

.. http:get:: $base/customers
.. http:get:: $base/customers/$id
.. http:post:: $base/customers
.. http:post:: $base/customers/$id
.. http:delete:: $base/customers/$id

Reports.
^^^^^^^^

Reports are persistent documents witnessing transactions.
A typical example is a Camt.053 statement.  A report lives
even after a bank account gets deleted or a customer leaves
the bank, therefore ``$base`` should only mention a demobank
instance.

.. http:get:: $base/reports
.. http:get:: $base/reports/$id
.. http:post:: $base/reports
.. http:post:: $base/reports/$id
.. http:delete:: $base/reports/$id