commit 22cbf5720f74b90c9d6aaef6d287a5d74bb87550 parent 078e4fb06ff7ea7f6b2173ca4924aa69e9bfceab Author: Florian Dold <florian@dold.me> Date: Tue, 2 Mar 2021 12:33:00 +0100 document base URLs / instances with examples Diffstat:
| M | core/api-merchant.rst | | | 66 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------- |
1 file changed, 58 insertions(+), 8 deletions(-)
diff --git 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