tos.rst (3381B)
1 -------------------- 2 Terms of service API 3 -------------------- 4 5 These APIs allow clients to obtain the terms of service 6 and the privacy policy of a service. 7 8 9 .. http:get:: /terms 10 11 Get the terms of service of the service. 12 The endpoint will consider the "Accept" and "Accept-Language" and 13 "Accept-Encoding" headers when generating a response. Specifically, 14 it will try to find a response with an acceptable mime-type, then 15 pick the version in the most preferred language of the user, and 16 finally apply compression if that is allowed by the client and 17 deemed beneficial. 18 19 The endpoint will set an "Etag", and subsequent requests of the same client 20 should provide the tag in an "If-None-Match" header to detect if the terms 21 of service have changed. If not, a "304 Not Modified" response will be 22 returned. Note that the "304 Not Modified" will also be returned if the 23 client changed the "Accept-Language" or "Accept-Encoding" header. Thus, if 24 the client would like to download the resource in a different language or 25 format, the "If-None-Match" header must be omitted. 26 27 If the "Etag" is missing, the client should not cache the response and 28 instead prompt the user again at the next opportunity. This is usually only 29 the case if the terms of service were not configured correctly. 30 31 The "Etag" is generated from the first 256 bits of the SHA-512 hash 32 over the terms and encoded in Crockford base-32. However, this behavior 33 is not normative and clients MUST NOT rely on it. 34 35 A "Taler-Terms-Version" header is generated to indicate the **legal** version 36 of the terms. This header will change whenever something **legally** changed 37 in the terms of service and the user must review and accept the terms of 38 service again. If the "Taler-Terms-Version" is identical to one that the 39 user has already accepted, there is no need for the user to review the terms 40 again. 41 42 When returning a full response (not a "304 Not Modified"), the server 43 should also include a "Avail-Languages" header which includes 44 a comma-separated list of the languages in which the terms of service 45 are available in (see `availability hints specification 46 <https://datatracker.ietf.org/doc/draft-nottingham-http-availability-hints/>`_). 47 Clients can use this to generate a language switcher 48 for users that may not have expressed a proper language preference. 49 50 **Response:** 51 52 :http:statuscode:`200 OK`: 53 The body is the terms of service in the requested 54 encoding and language. 55 :http:statuscode:`501 Not Implemented`: 56 The exchange lacks a valid terms of service 57 configuration. A human-readable error message 58 is returned. Wallets should not require the 59 human to accept any terms of service (and do not 60 need to show this message). 61 62 .. http:get:: /privacy 63 64 Get the privacy policy of the service. Behaves the same way as 65 The "/terms" endpoint, except that it returns the privacy policy 66 instead of the terms of service. 67 68 **Response:** 69 70 :http:statuscode:`200 OK`: 71 The body is the privacy policy in the requested 72 encoding and language. 73 :http:statuscode:`501 Not Implemented`: 74 The exchange lacks a valid terms of service 75 configuration. A human-readable error message 76 is returned. Wallets should not require the 77 human to accept any terms of service (and do not 78 need to show this message).