Interacting with third-party APIs is part of our DNA at Smooch. Whether it’s for a short-term hackathon project or to create a robust new integration within the Smooch platform, talking to APIs is what we do best.
We value stability, predictability and consistency in third-party APIs and those same attributes sit at the top of our priorities when developing our own API. Since the introduction of the Smooch API, we’ve been able to add new concepts and features while keeping the interface backwards compatible. However, there comes a point in the life of an API where backward incompatible changes need to be introduced so that considerable new capabilities can see the light.
We are excited to introduce a new API versioning mechanism on the Smooch platform. This new mechanism allows us to launch new features and make API improvements that require backwards incompatible changes while allowing you to opt in to these new capabilities on your own schedule.
How it works
There is no broadly adopted standard for API versioning so we’ve taken inspiration from other long-time API providers who have had to face similar challenges to us, such as Stripe and Facebook.
When making calls to the Smooch API you simply specify the version in the endpoint URL. For example: POST /v1/apps will call the v1 Create App API whereas POST /v1.1/apps will call the v1.1 version.
Webhook payloads are also versioned, following the same version progression as the API. You can specify which version Smooch should be using when calling your server during the webhook creation. This can be done in the Smooch dashboard or by calling the corresponding Create Webhook API.
When will new API versions be introduced?
New API versions will only be released when backwards incompatible changes necessitate them. We make frequent changes to the Smooch platform to improve functionality, support new use cases and improve performance. The vast majority of those changes can be done in a backwards compatible way and your code must be ready to gracefully handle these changes.
In order to help you prepare, we’ve published a new guide that thoroughly documents changes that are considered backwards compatible. You can also read more about how our versioning scheme works so that you can adopt new versions of our platform as they become available.
v1.1 is now available
Our first version update introduces a few API enhancements and new message delivery webhooks including delivery confirmation events from third-party channels. You can read up about changes introduced to v1.1 and follow our upgrade guide to adopt this new API version. You can also find more details about our new delivery confirmation webhooks in our guide.
At the moment, we have no plans to deprecate v1 and we may support it indefinitely. In the event where we would decide to sunset this version, rest assured you will receive multiple communications prior to the v1 API becoming unavailable.
If you have any questions or feedback on versioning or need help in the upgrade process please let us know, we’re always happy to help.