API versioning
Figure Markets APIs use path-based versions (e.g. /api/v1/..., /api/v2/...) where applicable. The following policy applies across Public API, Partner API, and Trader API (REST and trading endpoints).
Stability within a version
- We do not remove fields from request or response bodies for a given API version.
- We do not change the type or meaning of existing keys for a given version (e.g. a field that is a string will not become a number or be repurposed).
You can rely on existing fields and types for the version you integrate against.
Additive changes
- We may add new fields to request or response bodies without introducing a new path version. New fields are additive; we do not remove or change existing fields when we add new ones.
- We may add new enum values to existing response fields without introducing a new path version. If your code switches on an enum, handle unknown values gracefully (e.g. treat as “other” or log and continue) so that new values do not break you. We may revisit this policy.
- Client code that ignores unknown fields will continue to work. If you strictly parse only known keys, new optional fields will not break you.
When we use a new version
A new path version (e.g. v2) is introduced when we need to make breaking changes (e.g. removing or renaming a field, changing a type, or changing behavior in a way that is not backward compatible). When that happens, we document the change and the new version; the previous version remains supported for a documented period where applicable.
Summary
| Change | New version required? |
|---|---|
| Add new optional (or new required) fields | No |
| Add new enum values to an existing field | No (handle unknown values in your code; we may revisit) |
| Remove a field | Yes |
| Change type or meaning of an existing key | Yes |
| Add new endpoints | No |