DD 38

1 files changed, 94 insertions, 0 deletions

diff --git a/design-documents/038-demobanks-protocol-suppliers.rst b/design-documents/038-demobanks-protocol-suppliers.rst
new file mode 100644
index 00000000..82ce5e0f
--- /dev/null
+++ b/design-documents/038-demobanks-protocol-suppliers.rst
@@ -0,0 +1,94 @@
+DD 38: Demobanks protocol suppliers.
+####################################
+
+Summary
+=======
+
+This document models the association between financial data
+held in a LibEuFin *demobank* and the interface to let users
+access such financial data.
+
+Motivation
+==========
+
+LibEuFin Sandbox offers multitenency banking by the means of
+'demobanks'.  Each demobank offers access to financial data via
+*several* APIs.  The objective is to model such APIs so that each
+operation impacts one and only one demobank.
+
+Definitions
+===========
+
+Each API to access financial data at one demobank is offered by
+a **resource** called *protocol supplier*.  Therefore protocol
+suppliers MAY be subject to all the CRUD operations
+
+For each request that a protocol supplier serves, the demobank
+being impacted can be found in the following ways:
+
+.. _demobank-mutually-exclusive:
+
+1.  In a value that belongs to the request.
+2.  In a value that belongs to the protocol supplier's state.
+3.  Relying on the default demobank.
+
+Note: the three elements are mutually exclusive, so as to reduce
+ambiguity and simplify the implementation.
+
+Suppliers creation
+==================
+
+Suppliers can be hard-coded into the software or created RESTfully.
+
+Hard-coded
+^^^^^^^^^^
+
+This supplier never changes its state.  Whether this type
+of supplier is associated or not with a particular demobank
+MUST be stated in the documentation.
+
+Examples
+--------
+
+1.  A JSON-based protocol that lets users access their bank accounts
+always under the 'default' demobank belongs to this category.  It
+is therefore a 'hard-coded protocol supplier' with static demobank.
+
+2.  A XML-based protocol that lets users access their bank accounts
+in a demobank whose name appear in the URI is as well a 'hard-coded
+protocol supplier' but with dynamic demobank.
+
+Note: the upcoming (in version 0.9.3) JSON-based supplier that will
+let Nexus reach Sandbox accounts is planned as 'hard-coded protocol
+supplier' with dynamic demobank.  That allows Taler demos to only
+speak JSON.
+
+RESTful
+^^^^^^^
+
+This supplier has a name and its state CAN refer to one
+particular demobank.  These suppliers need to be created
+first, in order to be used.
+
+Examples
+--------
+
+1.  A JSON-based protocol that lets users access their bank
+accounts under the demobank whose name is held in the supplier
+state belongs to this category.  It is therefore a RESTful
+supplier with semi-dynamic demobank.
+
+2.  A XML-based protocol that lets user access their bank
+accounts under the demobank whose name is held both in the
+supplier state *and* in the URI is **wrong**.  This supplier
+doesn't respect this `mutual exclusivity <demobank-mutually-exclusive_>`_.
+
+3.  A XML-based protocol that lets user access their bank accounts
+always under the 'default' demobank belongs to this category.  It
+is a RESTful supplier with static demobank.  Note: this is the case
+of EBICS access offered in LibEuFin 0.9.2.
+
+Supplier reachability
+=====================
+
+Each supplier must be available under its own URI.