Best Practices

🔄 Keep Your Integration Up-to-Date

Falcon's API is continuously evolving, with frequent enhancements and new endpoints. To ensure your application benefits from the latest features and maintains compatibility:​

• Use the Latest API Version: Always integrate with the most recent API version to access new resources and improvements.
• Monitor the Changelog: Regularly check Falcon's Changelog for updates and modifications.​

By staying present, your application will align with the experiences provided in Falcon-integrated merchant applications.​

🔍 Anticipate and Handle API Changes

Understanding the nature of API changes is crucial for maintaining a robust integration. Falcon categorizes changes as follows:

⚠️ Breaking Changes

These changes may disrupt existing integrations, and we communicate them in advance through the developer changelog and other channels. However, exceptions apply to non-production staging APIs, where changes may occur without prior notice. Breaking changes include:​

• Removal of a field from an API response.
• Changing the data type of a field.
• Altering the structure of an object.
• Removal of an entire endpoint.
• Adding a new required field to a POST/PUT body.​

✅ Non-Breaking Changes

These changes are backward-compatible and do not require prior notification. To ensure stability:​

• Design Flexible Integrations: Implement code that gracefully handles additional fields or endpoints.
• Expect Enhancements: Be prepared for the following non-breaking changes:
  • Addition of new fields to GET responses.
  • Introduction of new optional fields in POST/PUT bodies.
  • Deployment of new endpoints.​

By anticipating these changes, your integration will remain stable and functional as Falcon's API evolves.

🧰 Developer Recommendations

To build a resilient and future-proof integration:

• Implement Error Handling: Ensure your application can handle unexpected fields or endpoints without failure.
• Regularly Update Dependencies: Keep your SDKs and libraries up-to-date to benefit from the latest fixes and features.

These best practices will ensure a robust and efficient integration with Falcon's platform.