Versions and Compatibility

New API Versions

Occasionally, Vibes Mobile Engagement Platform expansion and improvements may be so extensive to the existing APIs that the changes can't be made forward compatible. In that case, a new version of the APIs will be defined, and both versions will be available for a time to give you the opportunity to upgrade to the new version.

There are currently two versions of the APIs available. You can see what version you are using by looking at the API header.

X-API-Version: 1

Version 1

This is the default version. It does not accept the international format, E.164 phone numbers.

Version 2

To fully serve its international customers, Vibes released version 2 of the Vibes Mobile Engagement Platform APIs in 2016 to include support for international E.164 phone numbers.

Forward Compatible Changes

Occasionally, Vibes will add new elements and/or attributes to an existing API call within the existing version. These changes should be forward compatible with any existing code, as any new items added will be optional and/or have a default if not specified.

API Caller Best Practices

To ensure compatibility and avoid any tight coupling of your code with the Vibes Mobile Engagement Platform APIs, ensure that your code can accept/ignore any new elements or attributes in the JSON schema, both in API return values as well as any callback methods. The following are some best practices:

• Only get/bind the data that you need: Sometimes referred to as Duck Typing, when retrieving data from an API block, it's generally better to retrieve the specific data elements you use rather than trying to map or convert the entire object. The more that you can utilize Duck Typing, the lower coupling you'll have with the Platform.
• Utilize JSON URLs whenever possible: Item references in the Platform APIs include the REST URL to retrieve them. Whenever possible, utilize the URL that is returned rather than hard coding URL paths in the code.
• Avoid strict binding tools: There are binding/code generating tools that will map data to a class and bind the data to the object. Some of these libraries are strictly coupling tools in that a new attribute in the JSON data will throw an Exception if it doesn't exist in the class. Some libraries have an option to ignore the strict coupling, so that should be set if it exists. Otherwise, avoid these tools.
• Create tests with extra (random) elements: After you have the basic test for an API call, add an extra test that has an additional element and attribute in it. If your code continues to function with these extra elements, then the code is forward compatible. If the code breaks, or you get an Exception about a missing element in class, then you should rethink the approach.