commit a3c99f8cc976c9fa41e2c87cff4fbe7e01990233
parent 449d41231fdda77a38ca6cb2d5ac714013543edb
Author: Pius Loosli <loosp2@bfh.ch>
Date: Mon, 16 Oct 2023 14:47:53 +0200
Donau: small changes
Diffstat:
1 file changed, 17 insertions(+), 22 deletions(-)
diff --git a/core/api-donau.rst b/core/api-donau.rst
@@ -14,6 +14,7 @@
TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
@author Christian Grothoff
+ @author Pius Loosli
=====================
The Donau RESTful API
@@ -34,9 +35,9 @@ API Overview
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.
-The chapters group the families of requests frequently encountered when using the donau API:
+The chapters group the families of requests frequently encountered when using the Donau API:
-* :ref:`Status information<donau_status>`: get the public signing keys of the donau, the donation unit key, the donaus config or some entropy
+* :ref:`Status information<donau_status>`: get the public signing keys of the Donau, the donation unit key, the Donaus config or some entropy
* :ref:`Issue receipts<donau_issue>`: For use by charities: Issue receipts for blinded unique donor ids.
* :ref:`Submit receipts<donau_submit>`: Receive the receipts and, if valid, add all of it's donation units to the donor total. Returns a signature on the total yearly donation amount, hash of taxid+salt and year.
* :ref:`Charity administration and status information<donau_charity>`:
@@ -94,13 +95,13 @@ long-term offline signing key of the Donau, which clients should cache.
// The format is "current:revision:age".
version: string;
- // Financial domain this donau operates for.
+ // Financial domain this Donau operates for.
domain: string;
- // The donau's base URL.
+ // The Donau's base URL.
base_url: string;
- // The donau's currency.
+ // The Donau's currency.
currency: string;
// How many digits should the amounts be rendered
@@ -109,7 +110,7 @@ long-term offline signing key of the Donau, which clients should cache.
// given here (like on gas stations).
currency_fraction_digits: Integer;
- // Donation Units offered by this donau
+ // Donation Units offered by this Donau
donation_units: DonationUnitKeyGroup[];
// The Donau's signing keys.
@@ -196,7 +197,7 @@ long-term offline signing key of the Donau, which clients should cache.
.. ts:def:: SignKey
interface SignKey {
- // The actual donau's EdDSA signing public key.
+ // The actual Donau's EdDSA signing public key.
key: EddsaPublicKey;
// Initial validity date for the signing key.
@@ -240,10 +241,10 @@ long-term offline signing key of the Donau, which clients should cache.
// Name of the protocol.
name: "taler-donau";
- // Currency supported by this donau.
+ // Currency supported by this Donau.
currency: string;
- // Financial domain by this donau.
+ // Financial domain by this Donau.
domain: string;
}
@@ -257,15 +258,15 @@ Issue receipts
Inspired by the Taler exchange :ref:`Withdrawal<exchange-withdrawal>`.
-This API is used by the charity to obtain valid, attested donation receipts from the donau.
+This API is used by the charity to obtain valid, attested donation receipts from the Donau.
Use the :ref:`charity GET route<donau_charity_get>` to see the remaining donation volume for the current year.
-All incoming `BDID` are recorded under the corresponding charity_id by the donau.
+All incoming `BDID` are recorded under the corresponding charity_id by the Donau.
.. http:POST:: /batch-issue/$CHARITY_ID
- Send in a `IssueReceiptsRequest` and ask the donau to sign all it's contained `DonationUnit`.
+ Send in a `IssueReceiptsRequest` and ask the Donau to sign all it's contained `DonationUnit`.
**Request:** `IssueReceiptsRequest`
@@ -273,12 +274,10 @@ All incoming `BDID` are recorded under the corresponding charity_id by the donau
:http:statuscode:`200 OK`:
The request was successful, and the response is a `BSDonationReceipts`.
- :http:statuscode:`400 Bad request`:
- The charity content is malformed.
:http:statuscode:`403 Forbidden`:
The charity signature is invalid. This response comes with a standard `ErrorDetail` response.
:http:statuscode:`404 Not found`:
- At least one of the donation unit keys is not known to the donau. Comes with a `DonationUnitUnknownError`. This suggests a bug in the donor as it should have used current donation unit keys from :ref:`/keys<donau_status>`.
+ At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`. This suggests a bug in the donor as it should have used current donation unit keys from :ref:`/keys<donau_status>`.
:http:statuscode:`409 Conflict`:
The donation volume of the charity is not sufficient to issue donation receipts vor all sent in blinded udids. The response is a `IssueError` object.
:http:statuscode:`410 Gone`:
@@ -298,9 +297,7 @@ All incoming `BDID` are recorded under the corresponding charity_id by the donau
interface BDID {
donau_pub_hash: HashCode;
- taxpayer_blinded_id: BDIDEnvelope;
- // already in BDIDenvelope
- // blinded_unique_donor_id: HashCode; // NO: needs to be blinded hash: FDH_n(H(taxid,salt), nonce) * b^e mod n
+ taxpayer_blinded_id: BDIDEnvelope;
}
.. ts:def:: BDIDEnvelope
@@ -431,8 +428,6 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
:http:statuscode:`200 OK`:
The request was successful, and the response is a `SubmitResponse`.
- :http:statuscode:`400 Bad request`:
- The `SubmitRequest` is malformed.
:http:statuscode:`403 Forbidden`:
One of the signatures is invalid. This response comes with a standard `ErrorDetail` response.
:http:statuscode:`404 Not found`:
@@ -526,9 +521,9 @@ Charity administration and status information
**Response:**
:http:statuscode:`200 OK`:
- The donau responds with a `Charity` object
+ The Donau responds with a `Charity` object
:http:statuscode:`404 Not found`:
- The charity id does not belong to a charity known to the donau.
+ The charity id does not belong to a charity known to the Donau.
.. ts:def:: Charity
