Conventions

Type Aliases & Branding

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.

Pagination

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:

1
ResourcePage:
2
  items: T[]
3
  next_page_token: PageToken | None
4
  prev_page_token: PageToken | None

Decimals

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.

Unions

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.