taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

get-monitoring-historic-denomination-revenue.rst (2865B)

      1 .. http:get:: /monitoring/historic-denomination-revenues
      2 
      3   Get a list of historic denomination revenue stored by the auditor.
      4 
      5   A denomination is booked here once its legal period is over, so that the
      6   entry is final.  There can nonetheless be more than one entry per
      7   denomination: if the exchange moves value on a denomination that was
      8   already booked, the auditor appends the additional revenue as another
      9   entry instead of changing the one it already published.
     10 
     11   The following query parameters are optional, and can be used to customise the response:
     12 
     13   **Request:**
     14 
     15   Pagination follows the :ref:`row-id-pagination` convention.  The non-zero signed
     16   ``limit`` defaults to ``-20``.
     17 
     18   :query limit: Optional non-zero signed number of records; negative values request descending row IDs.
     19   :query offset: Optional :ts:type:`SafeUint64` row ID from which to begin.
     20 
     21   With the default settings, the endpoint returns at most the 20 latest elements.
     22 
     23   **Response:**
     24 
     25   :http:statuscode:`200 OK`:
     26     The auditor responds with a :ts:type:`HistoricDenominationRevenueResponse` object. Its ``records`` field is empty if no matching elements were found.
     27   :http:statuscode:`400 Bad request`:
     28     The request is malformed. Returned with an
     29     ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` error code.
     30   :http:statuscode:`401 Unauthorized`:
     31     The request lacks valid authentication credentials.
     32     The response comes with a ``TALER_EC_AUDITOR_GENERIC_UNAUTHORIZED``.
     33   :http:statuscode:`500 Internal Server Error`:
     34     The server experienced an internal error.
     35     The response comes with a ``TALER_EC_GENERIC_DB_SETUP_FAILED``,
     36     ``TALER_EC_GENERIC_DB_FETCH_FAILED``, or
     37     ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE`` error code.
     38 
     39   **Details:**
     40 
     41   .. ts:def:: HistoricDenominationRevenueResponse
     42 
     43     interface HistoricDenominationRevenueResponse {
     44 
     45       records: HistoricDenominationRevenue[];
     46 
     47     }
     48 
     49   .. ts:def:: HistoricDenominationRevenue
     50 
     51     interface HistoricDenominationRevenue {
     52 
     53       // Unique row identifier
     54       row_id : SafeUint64;
     55 
     56       // Hash code of the denomination public key involved
     57       h_denom_pub : HashCode;
     58 
     59       // Time when the denomination expired for deposits.  Note that
     60       // the revenue is only booked once the legal period of the
     61       // denomination is over as well.
     62       revenue_timestamp : Timestamp;
     63 
     64       // Total fee revenue the exchange earned from coins of this
     65       // denomination.
     66       revenue_balance : Amount;
     67 
     68       // Total losses the exchange experienced from this denomination
     69       // (this basically only happens if someone was able to forge
     70       // denomination signatures). So non-zero values are indicative
     71       // of a serious problem.
     72       loss_balance : Amount;
     73 
     74     }
     75 
     76   .. note::
     77 
     78     This endpoint is still experimental. The endpoint will be further developed as needed.