[taler-docs] branch master updated: document /terms endpoint

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new e77ad2d  document /terms endpoint
e77ad2d is described below

commit e77ad2d80d240ba1cc8fb286fe8a7af56b881ee9
Author: Christian Grothoff <address@hidden>
AuthorDate: Mon Dec 2 21:55:17 2019 +0100

    document /terms endpoint
---
 core/api-exchange.rst     | 16 +++++++++++++
 taler-exchange-manual.rst | 60 ++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 75 insertions(+), 1 deletion(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 66ec92a..13c35d5 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -41,6 +41,22 @@ hard-coded into the wallet as they are the trust anchors for 
Taler; (3)
 possibly by using HTTPS.
 
 
+.. http:get:: /terms
+
+  Get the terms of service of the exchange.
+  The exchange will consider the "Accept" and "Accept-Language" and
+  "Accept-Encoding" headers when generating a response. Specifically,
+  it will try to find a response with an acceptable mime-type, then
+  pick the version in the most preferred language of the user, and
+  finally apply compression if that is allowed by the client and
+  deemed beneficial.
+
+  The exchange will set an "Etag", and subsequent requests of the
+  same client should provide the tag in an "If-None-Match" header
+  to detect if the terms of service have changed.  If not, a
+  "204 Not Modified" response will be returned.
+
+
 .. http:get:: /keys
 
   Get a list of all denomination keys offered by the bank,
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index 4a57edc..e12c456 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -620,11 +620,70 @@ To change these settings, edit the following values in 
section
    ``taler-exchange-keyup`` will generate a quantity of signing keys
    which is sufficient to cover all the gap.
 
+
+Terms of Service
+----------------
+
+The exchange has an endpoint "/terms" to return the terms of service
+(in legal language) of the exchange operator.  The wallet will show
+those terms of service to the user when the user is first withdrawing
+coins.  Terms of service are optional for experimental deployments,
+if none are configured, the exchange will return a simple statement
+saying that there are no terms of service available.
+
+To configure the terms of service response, there are two options
+in the [exchange] section:
+
+-   TERMS_ETAG: The current "Etag" to return for the terms of service.
+    This value must be changed whenever the terms of service are
+    updated. A common value to use would be a version number.
+    Note that if you change the TERMS_ETAG, you MUST also provide
+    the respective files in TERMS_DIR (see below).
+-   TERMS_DIR: The directory that contains the terms of service.
+    The files in the directory must be readable to the exchange
+    process.
+
+The TERMS_DIR directory structure must follow a particular layout.
+First, inside of TERMS_DIR, there should be sub-directories using
+two-letter language codes like "en", "de", or "jp".  Each of these
+directories would then hold translations of the current terms of
+service into the respective language.  Empty directories are
+permitted in case translations are not available.
+
+Then, inside each language directory, files with the name of the
+value set as the TERMS_ETAG must be provided. The extension of
+each of the files should be typical for the respective mime type.
+The set of supported mime types is currently hard-coded in the
+exchange, and includes HTML, PDF and TXT files. If other files are
+present, the exchange may show a warning on startup.
+
+Example
+~~~~~~~
+
+A sample file structure for a TERMS_ETAG of "v1" would be:
+
+-   TERMS_DIR/en/v1.txt
+-   TERMS_DIR/en/v1.html
+-   TERMS_DIR/en/v1.pdf
+-   TERMS_DIR/de/v1.txt
+-   TERMS_DIR/de/v1.html
+-   TERMS_DIR/de/v1.pdf
+-   TERMS_DIR/fr/v1.pdf
+
+If the user requests an HTML with language preferences "fr" followed by "en",
+the exchange would return "TERMS_DIR/en/v1.html" lacking an HTML version in
+French.
+
+
 .. _Deployment:
 
 Deployment
 ==========
 
+This chapter describes how to deploy the exchange once it has been
+properly configured.
+
+
 .. _Keys-generation:
 
 Keys generation
@@ -865,4 +924,3 @@ TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS purpose.
 
 .. [3]
    https://api.taler.net/api-exchange.html#wire-req
-

-- 
To stop receiving notification emails like this one, please contact
address@hidden.