[taler-docs] branch master updated: document base URLs / instances with examples

[gnunet]

This is an automated email from the git hooks/post-receive script.

dold pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 22cbf57  document base URLs / instances with examples
22cbf57 is described below

commit 22cbf5720f74b90c9d6aaef6d287a5d74bb87550
Author: Florian Dold <florian@dold.me>
AuthorDate: Tue Mar 2 12:33:00 2021 +0100

    document base URLs / instances with examples
---
 core/api-merchant.rst | 66 ++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 58 insertions(+), 8 deletions(-)

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 5a9e6bf..8ab3bba 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -23,17 +23,67 @@
 Merchant Backend API
 ====================
 
-The ``*/private/*`` endpoints are only supposed to be exposed
-to the merchant internally, and must not be exposed on the
-Internet.
+.. contents:: Table of Contents
+
+-----------------------
+Base URLs and Instances
+-----------------------
 
-Most endpoints given here can be prefixed by a base URL that includes the
-specific instance selected (BASE_URL/instances/$INSTANCE/).  If
-``/instances/`` is missing from the request path, the ``default`` instance is
-used.
+A single merchant backend installation can host multiple merchant instances.
+This is useful when multiple businesses want to share the same payment
+infrastructure.
 
-.. contents:: Table of Contents
+Merchant backends have one special ``default`` instance.  This ``default``
+instance is used when no explicit instance is specified.
+
+Each instance (default and others) has a base URL.  The resources under
+this base URL are divided into to categories:
+
+* Public endpoints that are exposed to the Internet
+* Private endpoints (under ``/private/*``) that are only supposed to be exposed
+  to the merchant internally, and must not be exposed on the
+  Internet.
+
+To manage instances, private endpoints only available to the ``default``
+instance must be used.
+
+Examples:
+
+.. code-block:: none
+
+   Base URL of the merchant (default instance) at merchant-backend.example.com:
+   https://merchant-backend.example.com/
+
+   A private endpoint (default instance):
+   https://merchant-backend.example.com/private/orders
+
+   A public endpoint (default instance):
+   https://merchant-backend.example.com/orders
+
+   A private endpoint ("myinst" instance):
+   https://merchant-backend.example.com/instances/myinst/private/orders
+
+   A public endpoint ("myinst" instance):
+   https://merchant-backend.example.com/instances/myinst/orders
+
+   A private endpoint (explicit "default" instance):
+   https://merchant-backend.example.com/instances/default/private/orders
+
+   A public endpoint (explicit "default" instance):
+   https://merchant-backend.example.com/instances/default/orders
+
+   Endpoint(s) to manage other instances:
+   https://merchant-backend.example.com/private/instances
+   https://merchant-backend.example.com/instances/default/private/instances
+
+   Unavailabe endponts (will return 404)
+   https://merchant-backend.example.com/instances/myinst/private/instances
+
+--------------
+Authentication
+--------------
 
+TODO
 
 -----------------
 Configuration API

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.