From e77ad2d80d240ba1cc8fb286fe8a7af56b881ee9 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 2 Dec 2019 21:55:17 +0100 Subject: 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 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 - -- cgit v1.2.3