Versioning

Overview

We often make changes and roll out several new features on the MOLOCO Cloud APIs. These changes are nearly always backward compatible, however, some of them are inevitably backward incompatible. To mitigate the migration problem, we version for APIs and make those changes not to be directly applied to the latest stable version. Those changes are going to be bundled and released as the next version.

Changes introduced outside of a version release are documented in our change logs.

Release Schedules

MOLOCO releases a new API version every 3 months and each version will be supported for 9 months from the next version release. Hence, each version will be supported for at least 12 months.

Below is an example release schedule . We will notify you in prior to the version update through your Moloco representatives.

How to specify the version

You should specify the version of the API it is using.

curl https://api.moloco.cloud/cm/v1/campaigns \
  -H "Moloco-Cloud-Api-Version: v1.1" \

If you don't specify your version, we'll regard it as it is using the oldest stable version of APIs. For example, if the current supported versions are v1.1, v1.2, v1.3, then it'll be treated as v1.1.
To migrate to the newer version, please check if you handled all the changes made on the new version. The details of changes in each version could be find in the Release Notes.

❗️

Do not use multiple versions.

Please do not use different versions over the endpoints. We strongly suggest you use only a single version at a time.

Changes

We categorize the changes and decide whether the change will be directly applied to the service or released as the following version.

Breaking Changes

Breaking changes are any changes that require developer resources to maintain existing functionality. These changes will not affect the current stable versions and going to become effective as the new version. A list of breaking changes are things like:

• Removing or renaming a service, field, method, or enum value.
• Changing the type of a field.
• Change in behavior of endpoints.
  • Synchronous stats API becomes async.
  • Default behavior changes.
• Adding a new validation or changing an existing validation.
• Adding required params or changing optional param to required param.
• Adding a read/write field to a resource message.
• Changing the rate-limiting quota.
• Changing the error codes.

Non-Breaking Changes

Non-breaking changes are backward compatible changes. It will be released at any time without versioning. These changes could be made to the current stable versions. A list of non-breaking changes are things like:

• A new resource or API endpoint.
• A new optional request parameter.
• A new field in the response (not a field in the resource).
• A new enum value is only used in the request.
• A new enum value for the resource and response.
  • Please handle the new enum value that the API client is not aware of on the client side properly. Ex) regarding it as an unknown value.
  • Please keep the same enum value that the API client is not aware of when you send it back to the server. (Ex. Update resource with PUT APIs).
• A new read-only field in the resource.
• Changing the error message.