commit 71782e169175c3741755455419ed9f252fbf7743
parent b0687b27250fd57014c7146b7944c9d1ab69f1ec
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Thu, 27 Mar 2025 15:39:13 +0900
spec protocol vSTATISTICS
Diffstat:
| M | core/api-merchant.rst | | | 132 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- |
1 file changed, 130 insertions(+), 2 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -1,6 +1,6 @@
..
This file is part of GNU TALER.
- Copyright (C) 2014-2024 Taler Systems SA
+ Copyright (C) 2014-2025 Taler Systems SA
TALER is free software; you can redistribute it and/or modify it under the
terms of the GNU Affero General Public License as published by the Free Software
@@ -1402,6 +1402,134 @@ Inspecting instances
}
+Getting statistics
+------------------
+
+.. http:get:: /management/instances/$INSTANCE/statistics-amount/$SLUG
+.. http:get:: [/instances/$INSTANCE]/private/statistics-amount/$SLUG
+
+ This request will return be used to statistics where the
+ values are amounts. All available values for the given
+ SLUG will be returned.
+ Since protocol **vSTATISTICS**.
+
+ **Request:**
+
+ :query by: *Optional*. If set to "BUCKET", only statistics by bucket will be returned. If set to "INTERVAL", only staistics kept by interval will be returned. If not set or set to "ANY", both will be returned.
+ **Response:**
+
+ :http:statuscode:`200 Ok`:
+ The body will be a `MerchantStatisticsAmountResponse`
+ :http:statuscode:`401 Unauthorized`:
+ The request is unauthorized.
+ :http:statuscode:`404 Not found`:
+ The instance is unknown to the backend.
+
+ **Details:**
+
+ .. ts:def:: MerchantStatisticsAmountResponse
+
+ interface MerchantStatisticsAmountResponse {
+
+ // Statistics kept for a particular fixed time window.
+ buckets: MerchantStatisticAmountByBucket[];
+
+ // Statistics kept for a particular sliding interval.
+ intervals: MerchantStatisticAmountByInterval[];
+
+ }
+
+ .. ts:def:: MerchantStatisticAmountByBucket {
+
+ // Start time of the bucket (inclusive)
+ start_time: Timestamp;
+
+ // End time of the bucket (exclusive)
+ end_time: Timestamp;
+
+ // Range of the bucket
+ range: StatisticBucketRange;
+
+ // Sum of all amounts falling under the given
+ // SLUG within this timeframe.
+ cumulative_amounts: Amount[];
+ }
+
+ .. ts:def:: MerchantStatisticAmountByInterval {
+
+ // Start time of the interval.
+ // The interval always ends at the response
+ // generation time.
+ start_time: Timestamp;
+
+ // Sum of all amounts falling under the given
+ // SLUG within this timeframe.
+ cumulative_amounts: Amount[];
+ }
+
+.. http:get:: /management/instances/$INSTANCE/statistics-counter/$SLUG
+.. http:get:: [/instances/$INSTANCE]/private/statistics-counter/$SLUG
+
+ This request will return be used to statistics where the
+ values are counters. All available values for the given
+ SLUG will be returned.
+ Since protocol **vSTATISTICS**.
+
+ **Request:**
+
+ :query by: *Optional*. If set to "BUCKET", only statistics by bucket will be returned. If set to "INTERVAL", only staistics kept by interval will be returned. If not set or set to "ANY", both will be returned.
+
+ **Response:**
+
+ :http:statuscode:`200 Ok`:
+ The body will be a `MerchantStatisticsCounterResponse`
+ :http:statuscode:`401 Unauthorized`:
+ The request is unauthorized.
+ :http:statuscode:`404 Not found`:
+ The instance is unknown to the backend.
+
+ **Details:**
+
+ .. ts:def:: MerchantStatisticsCounterResponse
+
+ interface MerchantStatisticsCounterResponse {
+
+ // Statistics kept for a particular fixed time window.
+ buckets: MerchantStatisticCounterByBucket[];
+
+ // Statistics kept for a particular sliding interval.
+ intervals: MerchantStatisticCounterByInterval[];
+
+ }
+
+ .. ts:def:: MerchantStatisticCounterByBucket {
+
+ // Start time of the bucket (inclusive)
+ start_time: Timestamp;
+
+ // End time of the bucket (exclusive)
+ end_time: Timestamp;
+
+ // Range of the bucket
+ range: StatisticBucketRange;
+
+ // Sum of all counters falling under the given
+ // SLUG within this timeframe.
+ cumulative_counter: Number;
+ }
+
+ .. ts:def:: MerchantStatisticCounterByBucket {
+
+ // Start time of the interval.
+ // The interval always ends at the response
+ // generation time.
+ start_time: Timestamp;
+
+ // Sum of all counters falling under the given
+ // SLUG within this timeframe.
+ cumulative_counter: Number;
+ }
+
Deleting instances
------------------
@@ -1423,7 +1551,7 @@ Deleting instances
:query purge: *Optional*. If set to YES, the instance will be fully
deleted. Otherwise only the private key would be deleted.
- **Response**
+ **Response:**
:http:statuscode:`204 No content`:
The backend has successfully removed the instance. The body is empty.
