Versioning

We believe versioning is a crucial part of our offering. By providing a consistent versioning scheme for our API & Webhooks we are able to help you manage and predict how our changes will impact your usage. When we have to change the API in a backwards-incompatible way, we release a new version to avoid breaking your integration. You can opt-in to the new version whenever you’re ready to upgrade.

This guide covers how versioning works at Sunshine Conversations and how to safely upgrade to new versions.

API versioning

When making calls to the Sunshine Conversations API you specify the version you want to use directly in the endpoint URL.

For example:

POST /v1.1/apps will call the v1.1 Create App API
POST /v2/apps will call the v2 Create App API

Webhook versioning

Webhooks naturally follow the same version and payload schema as the API. You specify which version Sunshine Conversations should be using when calling your webhook endpoint during the custom integration’s creation.

When creating a custom integration via the API use the corresponding endpoint. For example, to create a custom integration with the v2 API call:

POST /v2/apps/{appId}/integrations/

When creating a Webhook via the Sunshine Conversations dashboard select the desired version from the version dropdown.

custom integration version selector

Backwards compatible changes

We consider the following types of changes to be backwards compatible. In other words, these types of changes do not require a new version of the API. When writing code against Sunshine Conversations APIs and webhook payloads, take care to ensure that the types of changes listed below would not break any assumptions you make in your code. Your JSON parsing logic should be configured not to throw an error when an unexpected key is found, or when an enum contains a previously unknown value. Assume also that any JSON field returned as an array may contain multiple items in the future.

The list below applies to our REST API, webhook events, the SDK public API, and our API libraries:

Additive changes

  • Adding new fields or HTTP headers to existing API responses and webhook payloads
  • Adding new optional fields, query parameters, or HTTP headers to existing API request payloads
  • Adding new API endpoints or adding new methods on existing endpoints e.g. adding support for HTTP PUT to an existing API path
  • Introducing new types of messages, integrations or any other typed entity without changing the behavior of existing types (e.g. introducing a new message type of ‘location’ or a new integration type of ‘twitter’. For any code that processes entities with a type property, unknown types should be gracefully handled or ignored.)
  • Introducing new webhook triggers and client platforms (e.g. introducing new conversation:start webhook trigger, or a new client platform kakao. When handling webhook events your code should gracefully handle or ignore unknown webhook triggers or client platforms.)
  • Sending existing platform webhook triggers and message types as channels adopt new capabilities (e.g. to begin delivering conversation:read webhooks for Twitter clients as soon as the channel adopts the read notification capability

Formatting changes

  • Changing the format or length of primary id fields and keys without exceeding 255 characters (e.g. changing the string format or character length of user.id or key.secret)
  • Changing the order of fields in existing API responses and webhook payloads

Relaxing restrictions

  • Increasing the size or length restrictions on arrays or strings, or allowing certain characters which were previously disallowed
  • Accepting upload and transmission of new file and media types that had been previously rejected
  • Allowing new types on existing fields (e.g. allowing passing null to unset a field such as user.profile.displayName)

Error handling

  • Changing the string content of friendly error descriptions (e.g. changing the message in the error title or equivalent. Error handling behavior should be done based on error code.)
  • Changing the validation precedence of invalid HTTP requests (e.g. when sending a request that is both malformed and with invalid auth credentials, we may return either a status code of 400 Bad Request or 401 Unauthorized)
  • Promoting unclassified errors into categorized errors (e.g. when code is unhandled_error or uncategorized_error
  • Introducing new classifications of errors (e.g. in the error code or equivalent. Your code should be able to gracefully handle unknown error code values)
  • Changing the HTTP status code of unhandled API errors (e.g. changing 500 Internal Server Error to something more specific like 400 Bad Request or 401 Unauthorized)

Changelog

We maintain a changelog of backward incompatible change as part of our API reference documentation.

We also have a platform wide changelog that covers the API, Web and Mobile SDKs, Integrations, and the Web dashboard available here.

Upgrade guide

Before you start using a new API version, please make sure you are aware of the following:

API Libraries

If you are using one of our API libraries, you’ll need to update to the following version in order to start using the v2 API:

  • JavaScript: 9.0.0
  • Java: 6.0.0

Upgrading webhooks without downtime

To avoid missing messages for apps used in production, follow the steps below to upgrade your Webhooks to a new version.

  1. Modify your code to support the webhook schema changes mentioned in the API Changelog. You can use the version property included in all event payloads to conditionally execute code based on the webhook version. Your code is now capable of receiving both webhook versions, while ignoring the newer version for now.
  2. Once changes from step (1) are deployed, create a custom integration with the new version with the equivalent triggers as the webhook you wish to upgrade either by using the custom integration API or from the integration page.
  3. With both webhooks running, write and deploy code to accept payloads with the new version and ignore those with the old version.
  4. Once you are satisfied with the webhook upgrade, remove the webhook with the old version either by using the delete integration API or from the webhook integration page.
  5. At this point you may remove code specific to the old version.

Steps 2-5 should be tested in a non-production environment before they are applied to your production environment.