Sandbox API introduction.

1 files changed, 30 insertions, 23 deletions

diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index e9800b22..0e20f946 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -5,8 +5,13 @@
 Sandbox API
 ###########
 
-Demobanks.
-==========
+Sandbox emulates a minimal bank, to provide EBICS access to test
+`Taler <https://taler.net>`_.  The top-level API defines two main
+groups: `demobanks <Demobanks_>`_ and `legacy <Legacy API_>`_.
+Currently, `error types <error-types_>`_ are common to both groups.
+
+Demobanks
+=========
 
 Sandbox is designed to allow multiple *demobanks* being hosted,
 where every demobank can have its own configuration (including
@@ -15,12 +20,12 @@ only one demobank, named ``default``, is supported.  Such demobank
 activates the API segment ``/demobanks/default``, under which several
 APIs are then served.  The following sections describe all such APIs.
 
-Customer API.
-^^^^^^^^^^^^^
+Customer API
+^^^^^^^^^^^^
 
 This API allows CRUD operations on the bank's customers (also referred
 as 'users').  All the calls are allowed for the administrator, whereas
-**only** the `password change <customer-password-modification>`_ is allowed
+**only** the `password change <customer-password-modification_>`_ is allowed
 for ordinary customers.
 
 The following endpoints are served under ``/demobanks/default/customer-api``.
@@ -235,30 +240,30 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
    :http:statuscode:`409 Conflict`:
      A istitutional user (``admin`` or ``bank``) tried the operation.
 
-Access API.
-^^^^^^^^^^^
+Access API
+^^^^^^^^^^
 
 Every endpoint is served under ``/demobanks/default/access-api``.
 See :doc:`/core/api-bank-access`.  This API allows users to access
 their bank accounts and trigger Taler withdrawals.
 
-Integration API.
-^^^^^^^^^^^^^^^^
+Integration API
+^^^^^^^^^^^^^^^
 
 Every endpoint is served under ``/demobanks/default/integration-api``.
 See :doc:`/core/api-bank-integration`.  This API handles the communication
 with Taler wallets.
 
-Taler Wire Gateway API.
-^^^^^^^^^^^^^^^^^^^^^^^
+Taler Wire Gateway API
+^^^^^^^^^^^^^^^^^^^^^^
 
 Served under ``/demobanks/default/taler-wire-gateway``.  Currently,
 only the :ref:`admin/add-incoming <twg-admin-add-incoming>` endpoint
 is implemented.  This endpoint allows testing, but the rest of
 this API does never involve the Sandbox. 
 
-EBICS API.
-^^^^^^^^^^
+EBICS API
+^^^^^^^^^
 
 .. _demobank-create-ebics-subscriber:
 
@@ -295,8 +300,8 @@ EBICS API.
 
   The following endpoints are **not** served under the ``/demobank/default`` segment.
 
-Legacy API.
-===========
+Legacy API
+==========
 
 This was the first API offered by Sandbox.  It is used in
 some test cases.  One is hosted at the Wallet repository; other
@@ -306,8 +311,8 @@ Except of the main EBICS handler located at "/ebicsweb", all
 the EBICS calls have to authenticate the 'admin' user via
 the HTTP basic auth scheme.
 
-EBICS Hosts.
-^^^^^^^^^^^^
+EBICS Hosts
+^^^^^^^^^^^
 
 .. http:post:: /admin/ebics/hosts
 
@@ -349,8 +354,8 @@ EBICS Hosts.
    meant for tests (as the Sandbox itself is) and no backup will be
    produced along this operation.
 
-EBICS Subscribers.
-^^^^^^^^^^^^^^^^^^
+EBICS Subscribers
+^^^^^^^^^^^^^^^^^
 
 .. http:post:: /admin/ebics/bank-accounts
 
@@ -440,8 +445,8 @@ EBICS Subscribers.
 
      }
 
-Bank accounts.
-^^^^^^^^^^^^^^
+Bank accounts
+^^^^^^^^^^^^^
 
 The access to a particular bank account is granted either to the
 owner or to admin, via the HTTP basic auth scheme.  A 'owner' is
@@ -504,8 +509,8 @@ registration of customers is offered via the :doc:`/core/api-bank-access`.
 
   **Request:** :ts:type:`AdminBankAccount`
 
-Transactions.
-^^^^^^^^^^^^^
+Transactions
+^^^^^^^^^^^^
 
 .. http:get:: /admin/bank-accounts/$accountLabel/transactions
 
@@ -627,6 +632,8 @@ Transactions.
   mentioned in the request body.
 
 
+.. _error-types:
+
 ======
 Errors
 ======