move /withdrawal operations top-level as suggested by Sebastian

1 files changed, 20 insertions, 14 deletions

diff --git a/core/api-corebank.rst b/core/api-corebank.rst
index f10ba7d5..20f657d9 100644
--- a/core/api-corebank.rst
+++ b/core/api-corebank.rst
@@ -160,18 +160,18 @@ Account Management
      Input data was invalid.  For example, the client specified a invalid
      phone number or e-mail address.
    :http:statuscode:`403 Forbidden`:
-     The response should indicate one of the following reasons.     
+     The response should indicate one of the following reasons.
 
-   * A reserved username was attempted, like ``admin`` or ``bank``. 
+   * A reserved username was attempted, like ``admin`` or ``bank``.
    * An unauthorized user tried to create the account
 
-   :http:statuscode:`409 Conflict`: 
+   :http:statuscode:`409 Conflict`:
      The internal account payto URI or username already exists.
 
 .. _delete-account:
 
 .. http:delete:: /accounts/$USERNAME
-  
+
   Delete the account whose username is ``$USERNAME``.  The deletion
   succeeds only if the balance is *zero*.
 
@@ -371,10 +371,10 @@ Account Management
 
        // Available balance on the account.
        balance: Balance;
- 
+
        // payto://-URI of the account.
        payto_uri: string;
- 
+
        // Number indicating the max debit allowed for the requesting user.
        debit_threshold: Amount;
 
@@ -507,6 +507,8 @@ Taler Withdrawals
 
     interface BankAccountCreateWithdrawalResponse {
       // ID of the withdrawal, can be used to view/modify the withdrawal operation.
+      // This ID will be globally unique and grant control over the operation to
+      // abort or confirm it.
       withdrawal_id: string;
 
       // URI that can be passed to the wallet to initiate the withdrawal.
@@ -516,9 +518,10 @@ Taler Withdrawals
   :http:statuscode:`403 Forbidden`:
     The operation was rejected due to insufficient funds.
 
-.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}
+.. http:get:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}
 
-  Query the status of a withdrawal operation.
+  Query the status of a withdrawal operation. Does not require further
+  authentication as knowledge of the withdrawal ID serves as an authenticator.
 
   **Response**
 
@@ -552,18 +555,22 @@ Taler Withdrawals
     }
 
 
-.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/abort
+.. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/abort
 
-  Abort a withdrawal operation.  Has no effect on an already aborted withdrawal operation.
+  Abort a withdrawal operation.  Has no effect on an already aborted
+  withdrawal operation.  Does not require further authentication as knowledge
+  of the withdrawal ID serves as an authenticator.
 
   :http:statuscode:`200 OK`: The withdrawal operation has been aborted.  The response is an empty JSON object.
   :http:statuscode:`409 Conflict`:  The reserve operation has been confirmed previously and can't be aborted.
 
 
-.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/confirm
+.. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/confirm
 
-  Confirm a withdrawal operation.  Has no effect on an already confirmed withdrawal operation.
-  This call is responsible of wiring the funds to the exchange.
+  Confirm a withdrawal operation.  Has no effect on an already confirmed
+  withdrawal operation.  This call is responsible for wiring the funds to the
+  exchange.  Does not require further authentication as knowledge of the
+  withdrawal ID serves as an authenticator.
 
   **Response**
 
@@ -926,4 +933,3 @@ This is an optional feature, not all implementations of the API support it.
 
    EBICS base URL.  This URL allows clients to make EBICS requests to one of
    the configured EBICS hosts.
-