Skip to main content
The API is versioned in the path. Today there is one version:

​
What we can change without warning

These are additive, and your integration should tolerate them:
  • New fields on existing responses. Parse the fields you need and ignore the rest. Do not assert on an exact object shape.
  • New endpoints.
  • New optional request parameters.
  • New error codes, within the existing type values. Branch on type first, then handle the specific codes you care about, and treat anything unrecognised as a generic failure of that type.
  • Wording of message. It is written for a human reading a log. Never parse it.

​
What counts as breaking

These will not happen inside v1:
  • Removing or renaming a field, endpoint, or error type.
  • Changing a field’s type, including the units of a monetary amount.
  • Making an optional request parameter required.
  • Tightening validation so a request that used to succeed now fails.
If we need one of those, it goes in /v2, and /v1 keeps working.

​
Deprecation

If an endpoint is going away, in this order:
  1. It gets marked deprecated in this documentation and in the OpenAPI description.
  2. Responses start carrying a Deprecation header and a Sunset header with the removal date.
  3. We email the account owner for any key that has called it in the previous 30 days.
  4. At the earliest, it is removed six months after step 2.

​
Pinning a client

The OpenAPI description at api.setaside.money/v1/openapi.json is generated from the routes themselves, so it cannot drift from what is actually running. If you generate a client from it, regenerate periodically to pick up new endpoints. Nothing you already use will move. Money is always an integer number of cents, and it will stay that way inside v1. That is the field type most likely to trip up a client and the one least likely to change.