The Vibes Mobile Engagement Platform and its available APIs are growing and adding additional capabilities. We make every effort to minimize the impact of these changes to our customers. However, there may be times where improvements are so extensive that the changes cannot be made forward compatible. In those cases, a new version of the APIs will be defined.

Currently there are two versions of our APIs.

Version 1 – The default version of the APIs. This version does not accept E.164 phone numbers, and therefore cannot be used for international sends. If an E.164 MDN is used, you will receive an error.
Version 2 – The second version of our APIs includes support for international E.164 phone numbers.

You can see what version you are using by looking at the API header.

X-API-Version: 1

Best Practices for Forward Compatibility

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.

What's Included in Version 2?

E.164 phone number support

E.164 is the official format for all international phone numbers that includes a plus sign (+) followed by a country code (up to 3 characters) and phone number (up to 12 characters).

For example:

U.S.: +12025550132
U.K.: +441632960964
Brazil: +5511991234567

Version 2 of the following Platform APIs now accept and return phone numbers in the standard E.164 format.:

The following is a partial API example showing how the E.164 format is displayed.

{
   "person_id":"c5235a1-e243-42z7-979c-7f6234kl21b60",
   "external_person_id":"542342",
   "mobile_phone":{
      "mdn":"+12025550132",
      "carrier_code":"104"
   }

Please note:

Version 2 will only accept MDNs in E.164 format. MDNs without a country code will be considered invalid.
MDNs will also be returned in E.164 format in callbacks and responses.
If you use Version 1 of the Platform APIs, a countrynotsupported error will be returned if you query for a person with an MDN that does not follow the E.164 format, for example, if it is a U.S. number and you use 2135551234 instead of +12135551234.