taler-docs

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

get-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst (2742B)

      1 .. http:get:: [/instances/$INSTANCE]/private/tokenfamilies/$TOKEN_FAMILY_SLUG
      2 
      3   This is used to get detailed information about a specific token family.
      4 
      5   **Required permission:** ``tokenfamilies-read`` (see :ref:`Scopes <merchant-api-scopes>`)
      6 
      7   **Response:**
      8 
      9   :http:statuscode:`200 OK`:
     10     The merchant backend has successfully returned the detailed information
     11     about a specific token family. Returns a `TokenFamilyDetails`.
     12 
     13   :http:statuscode:`401 Unauthorized`:
     14     The request is unauthorized.
     15   :http:statuscode:`404 Not found`:
     16     The merchant backend is unaware of the token family or instance.
     17     Returned with ``TALER_EC_MERCHANT_GENERIC_TOKEN_FAMILY_UNKNOWN``.
     18   :http:statuscode:`500 Internal Server Error`:
     19     The server experienced an internal failure.
     20     Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED`` or
     21     ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``.
     22 
     23   **Details:**
     24 
     25   The `TokenFamilyDetails` object describes a configured token family.
     26 
     27   .. ts:def:: TokenFamilyDetails
     28 
     29     interface TokenFamilyDetails {
     30 
     31       // Identifier for the token family.
     32       slug: Slug;
     33 
     34       // Human-readable name for the token family.
     35       name: string;
     36 
     37       // Human-readable description for the token family.
     38       description: string;
     39 
     40       // Optional map from IETF BCP 47 language tags to localized descriptions.
     41       description_i18n?: { [lang_tag: string]: string };
     42 
     43       // Additional meta data, such as the ``trusted_domains``
     44       // or ``expected_domains``. Depends on the ``kind``.
     45       extra_data?: object;
     46 
     47       // Start time of the token family's validity period.
     48       // No token validities can start before this time
     49       // (but they could be sold before).
     50       valid_after: Timestamp;
     51 
     52       // End time of the token family's validity period.
     53       // No tokens will be accepted after this time.
     54       valid_before: Timestamp;
     55 
     56       // Validity duration of an issued token.
     57       duration: RelativeTime;
     58 
     59       // Rounding granularity for the start validity of keys.
     60       // The desired time is rounded down to a multiple of this
     61       // granularity and then the ``start_offset`` is added to
     62       // compute the actual start time of the token keys' validity.
     63       // The end is then computed by adding the ``duration``.
     64       validity_granularity: RelativeTime;
     65 
     66       // Offset in seconds to subtract from the start time rounded to ``validity_granularity``
     67       // to compute the actual start time for a key.
     68       start_offset: RelativeTime;
     69 
     70       // Kind of the token family.
     71       kind: TokenFamilyKind;
     72 
     73       // How many tokens have been issued for this family.
     74       issued: Integer;
     75 
     76       // How many tokens have been used for this family.
     77       used: Integer;
     78 
     79    }