Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Data types

Decimals

For certain values, it’s crucial to avoid treating them as floating-point numbers, which cannot accurately represent all decimal numbers. Floating-point arithmetic can introduce precision errors, making it unsuitable for precise values such as monetary amounts.

To ensure precision, we return decimal values as JSON strings. This forces API users to explicitly handle conversion, ensuring that they choose a data type that preserves decimal accuracy. For more information, refer to RFC7493.

  • Fractional Separator: A . (dot) is used for the fractional part, and no thousands separator is included.
  • Precision:
    • API responses return decimal values with up to 12 decimal places in the fractional part.
    • Inputs can include up to 28 digits, and will be rounded to 12 decimal places.
  • Range:
    • Maximum value: 10¹⁶
    • Minimum value: -10¹⁶
    • Exceptions may apply, and will be explicitly noted when applicable.

Strings

Most string values in the API are automatically trimmed of leading and trailing whitespace. Additionally, these string values must not contain any control characters, except some cases when tabs (\t) and newlines (\n) are allowed.

Each string field has specific minimum and maximum length requirements, which are detailed in the relevant API specifications.

Validity periods

In the API, several entities have an associated “validity period” which defines the time range during which the entity is considered valid. This period is represented by two fields: valid_from and valid_until.

  • Time bounds:

    • The valid_from field indicates when the validity period starts (inclusive).
    • The valid_until field indicates when the validity period ends (exclusive).
    • For example, if a subscription starts at 2023-11-01T00:00+01:00 and ends at 2023-12-01T00:00+01:00, it will be valid throughout November but not in December.
    • The valid_until date must always be later than the valid_from date.
    • In some cases a validity period cannot be “empty”, meaning valid_from and valid_until cannot be the same value.
    • The valid_until field can be null, which means the validity period continues indefinitely (i.e., valid until further notice).
    • In some cases, valid_from can also be null, meaning the validity period is valid from the past indefinitely. If both valid_from and valid_until are null, the entity is considered valid indefinitely (i.e., always valid).

  • Granularity:

    • Validity periods must be specified in whole minutes. Any seconds or fractions will be truncated by the API.
    • Note: For example, if you submit 2023-11-01T23:45:67.912343+01:00, the API will truncate the seconds, and it will become 2023-11-01T23:45:00+01:00.
    • This minute-level precision is intentional because the validity of things like subscriptions and tokens doesn’t benefit from precision beyond minutes. Finer granularity may cause confusion, especially in systems that don’t display seconds or fractions of seconds. As a result, subscriptions cannot begin and end within the same minute.