summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2019-12-02 21:55:17 +0100
committerChristian Grothoff <christian@grothoff.org>2019-12-02 21:55:28 +0100
commite77ad2d80d240ba1cc8fb286fe8a7af56b881ee9 (patch)
treee515977115e36abf9acaf39a7d12843bb18d8c65
parent77c00cf9f710c0cff1836782a7b16113e01b6d42 (diff)
downloaddocs-e77ad2d80d240ba1cc8fb286fe8a7af56b881ee9.tar.gz
docs-e77ad2d80d240ba1cc8fb286fe8a7af56b881ee9.tar.bz2
docs-e77ad2d80d240ba1cc8fb286fe8a7af56b881ee9.zip
document /terms endpoint
-rw-r--r--core/api-exchange.rst16
-rw-r--r--taler-exchange-manual.rst60
2 files changed, 75 insertions, 1 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 66ec92a5..13c35d5e 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 4a57edc1..e12c4562 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
-