taler-docs

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

get-aml-OFFICER_PUB-kyc-statistics-NAMES.rst (2970B)

      1 .. http:get:: /aml/$OFFICER_PUB/kyc-statistics/$NAMES
      2 
      3   Returns the number of KYC events matching the space-separated (!)
      4   list of given event types ``$NAMES`` in
      5   the specified time range.  Note that this query can be slow as the
      6   statistics are computed on-demand. (This is OK as such requests should be
      7   rare.)
      8 
      9   This endpoint was introduced in protocol **v20**. It was
     10   modified in **v30** revision 1 to accept a space-separated
     11   list of names instead of a single name and to return an array
     12   of results.
     13 
     14   **Request:**
     15 
     16   *Taler-AML-Officer-Signature*:
     17     The client must provide Base-32 encoded EdDSA signature with
     18     ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that this
     19     is merely a simple authentication mechanism, the details of the request are
     20     not protected by the signature.
     21 
     22   :query start_date=TIMESTAMP:
     23     *Optional*. Specifies the date when to
     24     start looking (inclusive). If not given, the start time of the
     25     exchange operation is used.  The TIMESTAMP is given
     26     in seconds since the UNIX epoch.
     27   :query end_date=TIMESTAMP:
     28     *Optional*. Specifies the date when to
     29     stop looking (exclusive). If not given, the current date is used.  The TIMESTAMP is given
     30     in seconds since the UNIX epoch.
     31 
     32   **Response:**
     33 
     34   :http:statuscode:`200 OK`:
     35     The responds will be an `AmlStatisticsResponse` message.
     36   :http:statuscode:`204 No content`:
     37     All the event counters are zero.
     38   :http:statuscode:`400 Bad Request`:
     39     The request is malformed. Cases include:
     40 
     41     - The ``$H_OFFICER_PUB`` path segment is malformed.
     42       This response comes with a standard `ErrorDetail` response with
     43       a code of ``TALER_EC_GENERIC_PATH_SEGMENT_MALFORMED``.
     44     - The required HTTP header with the signature is missing. Returned with
     45       ``TALER_EC_GENERIC_HTTP_HEADERS_MALFORMED``.
     46 
     47   :http:statuscode:`403 Forbidden`:
     48     Two cases:
     49 
     50     - The signature is invalid. Returned with a code of
     51       ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_GET_SIGNATURE_INVALID``.
     52     - The specific officer is unknown or disabled. Returned with a code of
     53       ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_ACCESS_DENIED``.
     54 
     55   :http:statuscode:`414 URI Too Long`:
     56     The statistics names string in the URL is too long.
     57     This response comes with a standard `ErrorDetail` response with
     58     a code of ``TALER_EC_GENERIC_URI_TOO_LONG``.
     59   :http:statuscode:`500 Internal server error`:
     60     The server had an internal problem handling the request.
     61     The error code is usually a ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
     62 
     63   **Details:**
     64 
     65   .. ts:def:: AmlStatisticsResponse
     66 
     67     interface AmlStatisticsResponse {
     68       // Statistics that were found.
     69       statistics: EventCounter[];
     70     }
     71 
     72 
     73   .. ts:def:: EventCounter
     74 
     75     interface EventCounter {
     76       // Name of the statistic that is being returned.
     77       event: string;
     78 
     79       // Number of events of the specified type in
     80       // the given range.
     81       counter: Integer;
     82 
     83     }