Overview

Moloco Ads APIs are updated on a regular basis to keep up with the changing needs of our users. Some of the changes are backward compatible while others aren't. Given that some of the updates are inevitably backward incompatible, we bundle these changes into a new version to prevent any compatibility issues. You can find a list of available versions and the backward incompatible changes for each available version in the release notes. Backward compatible changes can be found in the change logs.

API release plan

Our policy is to release a new version every 6 months. In the event that there are no breaking changes made during the 6 month period, release may be delayed another 6 months. The least recent version we support is deprecated every 6 months as well such that every version is supported for at least 12 months. See the release notes for the latest release schedule.

How to specify the version

When a version hasn't been specified, the system defaults to using the least recent version available. This means that you will be automatically using v1.3 when the available versions are v1.3, v1.4, and v1.5. Without having migrated to one of the later versions, you may be at risk of losing important data from breaking changes at the time the least recent version is deprecated. Users at risk of being impacted by an upcoming version deprecation are notified by email well ahead of time.

❗️

Important:

We strongly advise against specifying multiple API versions across a single organization. If you have multiple Moloco Ads API users in your organization, be sure that they are all using the same version.

When making an API request, you must specify the API version you would like to use as in the following example.

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

Types of changes to the APIs

Breaking changes

Breaking changes require developer resources to maintain existing functionality. As these changes aren't backward compatible, they aren't applied immediately but are instead accumulated over a timeframe of at least 6 months before being released in a bundle as a new API version. All breaking changes are documented in the release notes. Breaking changes include but aren't limited to the following.

• Removing or renaming a feature, property, method, or value of a property of the enum type.
• Changing the field type (e.g., string to enum).
• Changing the functionality of an endpoint (e.g., synchronous to asynchronous API, changes in default functionality, etc.)
• Adding a new validation or updating an existing validation.
• Adding additional required parameter(s) and/or changing parameter type from optional to required.
• Adding a read/write property to a resource message.
• Changing the API quota.
• Changing the error code(s).

Non-breaking changes

Non-breaking changes are backward compatible. They are applied immediately to all available API versions at the time of release. All non-breaking changes are documented in the change logs. Non-breaking changes include but aren't limited to the following.

• Adding a new resource or API endpoint.
• Adding a new optional request property.
• Adding a new property to the response (not the resource).
• Adding a new value for a property of the enum type that is only used in the request.
• Adding a new value for a property of the enum type to both the resource and response.

Note: On the client side, you must handle the new value for a property of the enum type that the API client isn't aware of (e.g., flag as an unknown value) and be sure to keep the same value when sending back to the server (e.g., update the API resource with PUT APIs).

• Adding a new read-only property to the resource.
• Changing the error message.