api-donau.rst (5508B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2014-2023 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3.0, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Christian Grothoff 17 @author Pius Loosli 18 @author Lukas Matyja 19 @author Johannes Casaburi 20 21 .. _donau-api: 22 23 ================= 24 Donau RESTful API 25 ================= 26 27 The API specified here follows the :ref:`general conventions <http-common>` 28 for all details not specified in the individual requests. 29 The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_ 30 defines all specific terms used in this section. 31 32 .. _donau-overview: 33 34 35 36 ------------ 37 API Overview 38 ------------ 39 40 This is intended to provide a quick overview of the whole REST API. For a more detailed view of the protocol, see the protocol specification. 41 42 The chapters group the families of requests frequently encountered when using the Donau API: 43 44 * :ref:`Status information<donau_status>`: get the public signing keys of the Donau, the donation unit key, the Donaus config or some entropy 45 * :ref:`Issue receipts<donau_issue>`: For use by charities: Issue receipts with blinded unique donor ids from a donor. 46 * :ref:`Donation statement<donation_statement>`: Summarizes the donation receipts to the donation statement signature which is made over the total yearly donation amount, 47 the year and the hash of taxid+salt. Provides an API to get the donation statement signature. 48 * :ref:`Charity administration and status information<donau_charity>`: 49 50 * For use by administrators to add/modify a charity 51 * For use by charities to get their remaining donation volume 52 53 54 --------------- 55 Version History 56 --------------- 57 58 The current protocol version is **v1**. 59 60 * The merchant is currently targeting protocol version **v0**. 61 * The donau validator app is currently targeting protocol version **v0**. 62 63 **Version history:** 64 65 * ``v0``: This is the first implementation. 66 * ``v1``: Adds ``build_version`` to GET ``/config`` 67 * ``v2``: answers a ``/batch-issue`` request that exceeds the charity's remaining yearly limit with 409 instead of 400 68 69 **Upcoming versions:** 70 71 * none 72 73 **Ideas for future version:** 74 75 * ``vXXX``: marker for features not yet targeted for release 76 77 78 .. include:: tos.rst 79 80 .. _donau_status: 81 82 ---------------------------------------- 83 Donau public keys and status information 84 ---------------------------------------- 85 86 This API is used by donors and charities to obtain global information about 87 the Donau, such as online signing keys and available donation units. This is 88 typically the first call any Donau client makes, as it returns information 89 required to process all of the other interactions with the Donau. The 90 returned information is secured by signature(s) from the Donau, especially the 91 long-term offline signing key of the Donau, which clients should cache. 92 93 .. include:: donau/get-keys.rst 94 95 .. include:: donau/get-seed.rst 96 97 .. include:: donau/get-config.rst 98 99 .. include:: donau/get-history.rst 100 101 102 .. _donau_issue: 103 104 -------------- 105 Issue receipts 106 -------------- 107 108 Inspired by the Taler exchange :ref:`Withdrawal<exchange-withdrawal>`. 109 110 This API is used to obtain valid, attested donation receipts from the Donau. 111 Use the :ref:`charity GET route<donau_charity_get>` to see the remaining donation volume for the current year. 112 113 CSR Issue 114 ~~~~~~~~~~~ 115 116 .. include:: donau/post-csr-issue.rst 117 118 119 Batch Issue 120 ~~~~~~~~~~~ 121 This is the effective issue receipts request. Depending on the amount of the donation a 122 certain amount of blinded unique donation identifiers, or for short BUDIs, are required. 123 Every BUDI will be signed by the corresponding requested donation unit, which is associated with a value. 124 This API is used by the charity but the array of `BlindedDonationReceiptKeyPair` are coming from the donor. 125 126 To make the request idempotent, the hash of the whole request is recorded under the 127 corresponding charity_id by the Donau. 128 129 .. include:: donau/post-batch-issue-CHARITY_ID.rst 130 131 .. _donation_statement: 132 133 ------------------ 134 Donation statement 135 ------------------ 136 137 Inspired by the Taler exchange :ref:`Deposit<deposit-par>`. 138 139 Donation statement operations are requested by a donor. 140 141 .. include:: donau/post-batch-submit.rst 142 143 .. include:: donau/get-donation-statement-YEAR-HASH_DONOR_ID.rst 144 145 .. _donau_charity: 146 147 --------------------------------------------- 148 Charity administration and status information 149 --------------------------------------------- 150 151 The administration requests require an authorized bearer token to be set in the HTTP "Authorization" Header. This token can be set by a proxy validating authentication/authorization (using e.g. LDAP). 152 The GET status requests require an authorized bearer token as well. 153 154 .. include:: donau/get-charities.rst 155 156 .. _donau_charity_get: 157 158 .. include:: donau/get-charity-CHARITY_ID.rst 159 160 .. include:: donau/post-charities.rst 161 162 .. include:: donau/patch-charities-CHARITY_ID.rst 163 164 .. include:: donau/delete-charities-CHARITY_ID.rst