API versioning
Redpin uses endpoint versioning to evolve our API while maintaining stability for existing integrations. This approach ensures your applications continue working without disruption while allowing you to adopt new features at your own pace.
Versioning approach
When backwards-incompatible changes are necessary, we create new endpoint versions with updated paths. For example, a breaking change to the payments endpoint results in /v2/payments rather than modifying /v1/payments.
This approach provides several benefits:
- Stability: Existing integrations continue functioning without modification
- Flexibility: Migrate to new versions on your timeline
- Clarity: Version numbers in the path make it explicit which API version you’re using
- Coexistence: Use different versions for different endpoints based on your needs
Breaking changes
We consider the following changes to be backwards-incompatible and will require a new endpoint version:
Removing or renaming fields
Removing existing fields from responses or renaming them to different names. This breaks clients that depend on the original field names.
Changing field data types
Modifying the data type of existing fields, such as changing a string to an integer or a number to a string. This can cause parsing errors in client applications.
Making parameters required
Changing previously optional request parameters to required. This breaks existing API calls that don’t include these parameters.
Modifying request/response structure
Changing the structure of request or response bodies in ways that affect how data is organized or accessed.
Changing authentication requirements
Modifying authentication or authorization requirements, including changes to required scopes or permissions.
Modifying error codes
Removing or changing the meaning of existing error codes that clients may be handling programmatically.
Altering endpoint behavior
Changing the behavior of existing endpoints in ways that could affect client logic or business processes.
When we introduce breaking changes, we create a new endpoint version and provide:
- Migration documentation in our Changelog
- Updated examples in the API Reference
- Guidance on adapting your integration
Previous endpoint versions remain available and supported, giving you time to plan and execute migration.
Backwards-compatible changes
Redpin considers the following changes to be backwards-compatible and applies them across all endpoint versions:
New endpoints
Adding new API endpoints or resources that don’t affect existing functionality.
Optional parameters
Adding new optional request parameters to existing endpoints.
New response properties
Adding new properties to existing API responses. Clients should ignore unknown fields.
Property ordering
Changing the order of properties in API responses. Clients should not depend on field order.
Enum values
Adding new values to existing enums where appropriate and documented.
Optional headers
Introducing new optional request or response headers.
We regularly introduce backwards-compatible changes to support new product features. These changes are applied across all endpoint versions, meaning you can access new functionality without upgrading to a newer version.
Your integration should be designed to handle backwards-compatible changes gracefully, such as ignoring unexpected response fields and not depending on field ordering.
Version migration
When a new endpoint version is released:
Review the changelog
Check the Changelog for details about what changed and why a new version was necessary.
Test in sandbox
Use the sandbox environment to test your integration with the new endpoint version before migrating production traffic.
Update your integration
Modify your application code to work with the new endpoint version, following the migration guidance provided.
Best practices
Design for forwards compatibility
Structure your integration to handle new fields and enum values gracefully:
- Ignore unknown fields in API responses
- Don’t rely on specific field ordering in responses
- Handle new enum values appropriately (e.g., with a default case)
- Validate response structures defensively
Stay informed
Subscribe to our changelog notifications to stay informed about new endpoint versions and upcoming changes. Major version releases are announced in advance with detailed migration guides.
Plan migrations proactively
While we maintain support for previous endpoint versions, plan to migrate to newer versions within a reasonable timeframe to:
- Access new features and capabilities
- Benefit from performance improvements
- Receive the latest security updates
- Ensure long-term supportability
Contact the Partner Integrations Team if you need assistance with version migration or have questions about specific changes.
