​
Overview

The API uses path-based major versioning and semantic versions in the spec:
  • Routing (breaking changes): /{api}/{v1}/...
    Example: /api/v1/liquidity/...
  • Documentation/SDK (non-routing): info.version uses SemVer (e.g., 2.0.1) to signal doc/SDK updates within the same major.
Pin to /v1 in your base URL to avoid surprises. We only bump the path major when introducing breaking changes.

​
Compatibility Guarantees (Non-breaking)

Within the same major (e.g., v1), we may ship changes that are backward-compatible. Your integration should continue to work if you:
  • Ignore unknown fields in responses.
  • Don’t assume enums are closed sets (handle new enum values gracefully).
Examples of non-breaking changes:
  • Adding new endpoints or resources
  • Adding optional request parameters
  • Making a required parameter optional
  • Adding new properties to response objects
  • Changing the order of properties in JSON
  • Adding new enum members (if clients treat unknown values safely)

​
What Counts as a Breaking Change

Changes that can require code updates or alter behavior in a way that can break existing clients. These will trigger a new major path (e.g., /v3):
  • Removing an endpoint, field, or enum value
  • Renaming fields or changing field types
  • Changing required parameters or tightening validation (e.g., narrower ranges, new mandatory header)
  • Altering response structure (e.g., changing pagination shape)
  • Changing default business logic in a way that affects results (e.g., default sort/filters, monetary rounding)
  • Changing error envelope format

​
Deprecation & Sunset Policy

When we plan to remove or alter behavior in a way that breaks compatibility:
  • We announce in the changelog and docs.
  • We add deprecation headers on affected endpoints where possible:
    • Deprecation: true
    • Sunset: <RFC 1123 date> (planned removal date)
    • Link: <https://docs.mansa.io/changelog#deprecations>; rel="deprecation"
  • We provide at least 90 days’ notice before removal (unless a security or compliance issue requires faster action).

​
Version Pinning

Always target a specific major: 
GET https://api.mansa.io/api/v1/liquidity/management/loans?limit=50&page=1
Authorization: Bearer <token>
X-API-Key: <key>
Do not rely on unversioned paths. Minor and patch updates within v1 won’t change routing or the error envelope.

​
Forward-Compatibility Tips

To minimize friction when we add features within a major:
  • Ignore unknown fields in JSON objects.
  • Treat enums as open; handle unexpected values by mapping to a safe fallback.
  • Validate inputs using the spec, but prefer soft validation where safe (to tolerate new optional params).
  • Use structured errors (error.type, error.code, param) rather than string-matching messages.

​
Upgrading to a New Major

When a new major path (e.g., /v3) is released:
  1. Review the Upgrade Guide in the changelog.
  2. Test critical flows against /v3 in staging.
  3. Roll out gradually; log and monitor error codes and rate limits.
  4. Switch production traffic once parity is confirmed.

​
Frequently Asked Questions

Q: Will you add fields to responses without a new version?
A: Yes—adding fields is non-breaking. Clients should ignore fields they don’t use. Q: Will enum values change?
A: We may add enum values in the same major. We won’t remove or rename existing ones without a new major. Q: How are errors versioned?
A: The error envelope shape is stable within a major ({ "error": { "type", "code", "message", ... } }). New error.code values may appear.