For many string or UUID types, you may notice we alias / brand them as their own type. Branding is a technique to preserve the underlying type but distinguish it as a new type, so it is easier to avoid mixing them up while developing.
This also allows us to communicate extra information to you about how they may be intended to be used. For example,
we brand decimal strings with the type Decimal to indicate that the server will parse them into Python
Decimal objects.
When using them in the API requests, these types all still serialize as JSON strings in the HTTP payload. However, if you are using our typed clients (SDK), the client will provide them to you as the branded type.
We use pagination in our API to make sure that we don’t return too much data at once. Many of our endpoints return
an extension of the ResourcePage type:
We avoid using floating-point arithmetic that leads to imprecision. Instead, we use the Decimal type,
which is a string alias type that represents a decimal number as a string. These decimal strings are parsed into the
Python Decimal class.
We use unions to represent a type that can be one of several different types. When a union shape is used, our
union discriminant will always be the type field unless otherwise specified.
We also expect that it is a non-breaking change to add a new union member to a union type. This means that if you
handle a union field in a response, we expect you to gracefully handle an _other case. This allows us
to better serve and improve our APIs at a quick velocity without breaking your code.