Donau: http status codes

1 files changed, 97 insertions, 75 deletions

diff --git a/core/api-donau.rst b/core/api-donau.rst
index 57a66603..69659eea 100644
--- a/core/api-donau.rst
+++ b/core/api-donau.rst
@@ -26,6 +26,8 @@ defines all specific terms used in this section.
 
 .. contents:: Table of Contents
 
+.. _donau-overview:
+
 ------------------------
 API Overview
 ------------------------
@@ -34,7 +36,7 @@ This is intended to provide a quick overview of the whole REST API. For a more d
 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 denomination unit key, the donaus config or some entropy
-* :ref:`Issue receipts<donau_attest>`: For use by charities: Issue receipts for blinded unique donor ids.
+* :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>`:
   
@@ -56,47 +58,6 @@ Donau.  The returned information is secured by signature(s) from the Donau,
 especially the long-term offline signing key of the Donau, which clients
 should cache.
 
-
-.. http:get:: /seed
-
-  Return an entropy seed. The Donau will return a high-entropy
-  value that will differ for every call.  The response is NOT in
-  JSON, but simply high-entropy binary data in the HTTP body.
-  This API should be used by wallets to guard themselves against
-  running on low-entropy (bad PRNG) hardware. Naturally, the entropy
-  returned MUST be mixed with locally generated entropy.
-
-
-.. http:get:: /config
-
-  Return the protocol version, financial domain and currency supported by this
-  Donau backend.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The body is a `VersionResponse`.
-
-  .. ts:def:: DonauVersionResponse
-
-    interface DonauVersionResponse {
-      // libtool-style representation of the Donau protocol version, see
-      // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
-      // The format is "current:revision:age".
-      version: string;
-
-      // Name of the protocol.
-      name: "taler-donau";
-
-      // Currency supported by this donau.
-      currency: string;
-
-      // Financial domain by this donau.
-      domain: string;
-
-    }
-
-
 .. http:get:: /keys
 
   Get a list of all donation units keys offered by the Donau,
@@ -248,8 +209,46 @@ should cache.
     Both the individual donation units *and* the denomination list is signed,
     allowing customers to prove that they received an inconsistent list.
 
+.. http:get:: /seed
 
-.. _donau_attest:
+  Return an entropy seed. The Donau will return a high-entropy
+  value that will differ for every call.  The response is NOT in
+  JSON, but simply high-entropy binary data in the HTTP body.
+  This API should be used by wallets to guard themselves against
+  running on low-entropy (bad PRNG) hardware. Naturally, the entropy
+  returned MUST be mixed with locally generated entropy.
+
+.. http:get:: /config
+
+  Return the protocol version, financial domain and currency supported by this
+  Donau backend.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The body is a `VersionResponse`.
+
+  .. ts:def:: DonauVersionResponse
+
+    interface DonauVersionResponse {
+      // libtool-style representation of the Donau protocol version, see
+      // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
+      // The format is "current:revision:age".
+      version: string;
+
+      // Name of the protocol.
+      name: "taler-donau";
+
+      // Currency supported by this donau.
+      currency: string;
+
+      // Financial domain by this donau.
+      domain: string;
+
+    }
+
+
+.. _donau_issue:
 
 ----------------------------------------
 Issue receipts
@@ -273,6 +272,16 @@ 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>`.
+  :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`:
+    The requested donation unit key is not yet or no longer valid. It either before the validity start, past the expiration or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code provided to understand which of the cases this is and handle it accordingly.
 
   **Details:**
 
@@ -318,14 +327,36 @@ All incoming `BDID` are recorded under the corresponding charity_id by the donau
       cs_blinded_c1: string; // Crockford Base32 encoded
     }
 
+  .. ts:def:: IssueError
+
+    interface IssueError{
+      max_per_year: Amount;
+      current_year: Amount;
+    }
+
+  .. ts:def:: DonationUnitUnknownError
+
+    interface DonationUnitUnknownError{
+      unknown_hash_pub_donation_unit: HashCode[];
+      donau_pub: EddsaPublicKey;
+      donau_sig: EddsaSignature;
+    }
+
+  .. ts:def:: DonationUnitExpiredMessage
+
+    interface DonationUnitExpiredMessage{
+      h_donation_unit_pub: HashCode;
+      donau_pub: EddsaPublicKey;
+      donau_sig: EddsaSignature;
+    }
+
 .. _donau_submit:
 
 -----------------------------
-Submit receipts (ex Deposit)
+Submit receipts
 -----------------------------
 Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
 
-
 .. http:POST:: /submit
   
   Send in donation receipts for the past fiscal year, receive signed total back.
@@ -336,6 +367,16 @@ 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`:
+    At least one of the donation unit keys is not known to the donau. Comes with a `DonationUnitUnknownError`.
+  :http:statuscode:`409 Conflict`:
+    The submit operation has failed because a unique donor id was already submitted. Comes with a `DonationReceiptDoubleSpendError`.
+  :http:statuscode:`410 Gone`:
+    The requested donation unit key is not yet or no longer valid. It either before the validity start, past the expiration or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code provided to understand which of the cases this is and handle it accordingly.
 
   **Details:**
 
@@ -363,36 +404,13 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
       // signature over taxid_hashed, total, year
       signature: EddsaSignature;
     }
-..   :http:statuscode:`200 OK`:
-..     The operation succeeded, the donau confirms that no double-spending took
-..     place.  The response will include a `BatchDepositSuccess` object.
-..   :http:statuscode:`403 Forbidden`:
-..     One of the signatures is invalid.
-..     This response comes with a standard `ErrorDetail` response.
-..   :http:statuscode:`404 Not found`:
-..     Either one of the denomination keys is not recognized (expired or invalid),
-..     or the wire type is not recognized.
-..     If a denomination key is unknown, the response will be
-..     a `DonationUnitUnknownMessage`.
-..   :http:statuscode:`409 Conflict`:
-..     The deposit operation has either failed because a receipt has insufficient
-..     residual value, or because the same public key of a receipt has been
-..     previously used with a different denomination.
-..     Which case it is
-..     can be decided by looking at the error code
-..     (``TALER_EC_DONAU_DEPOSIT_CONFLICTING_CONTRACT`` (same receipt used in different ways),
-..     ``TALER_EC_DONAU_GENERIC_INSUFFICIENT_FUNDS`` (balance insufficient) or
-..     ``TALER_EC_DONAU_GENERIC_RECEIPT_CONFLICTING_DENOMINATION_KEY``
-..     (same receipt public key, but different denomination)).
-..     The fields of the response are still evolving (see bug 7267),
-..     for now the format of the response is a `DepositDoubleSpendError`.
-..     The request should not be repeated again with this receipt.
-..   :http:statuscode:`410 Gone`:
-..     The requested denomination key is not yet or no longer valid.
-..     It either before the validity start, past the expiration or was revoked. The response is a
-..     `DonationUnitExpiredMessage`. Clients must evaluate
-..     the error code provided to understand which of the
-..     cases this is and handle it accordingly.
+
+  .. ts:def:: DonationReceiptDoubleSpendError
+
+    interface DonationReceiptDoubleSpendError{
+      doubleSpent: DonationReceipt[];
+    }
+
 
 .. _donau_charity:
 
@@ -457,6 +475,8 @@ Charity administration and status information
 
   :http:statuscode:`201 Created`:
     The request was successful, and the response is a `CharityResponse`.
+  :http:statuscode:`400 Bad request`:
+    The charity content is malformed.
 
   .. ts:def:: CharityRequest
   
@@ -484,6 +504,8 @@ Charity administration and status information
 
   :http:statuscode:`200 OK`:
     The request was successful.
+  :http:statuscode:`400 Bad request`:
+    The charity content is malformed.
 
 .. http:get:: /charities/$CHARITY_ID/history