Adobe Analytics 2.0 API changes in the last few weeks: any documentation?

[Biggsie415]

Happy New Year all!

I've been using the Reporting 2.0 API to power our Tableau dashboards for years. Since the Christmas break, I've noticed that all the API responses have changed and I can't find any API-specific documentation to learn more. Are more changes coming? What is the intention of the changes? 

For example, when requesting visits by week by tracking code, the response used to include the following data: 

data: list

itemId: str

value: str

Now, I see the addition of two lists:

data: list

itemId: str

itemIds: list

value: str

values: list

Any ideas? 

[Jennifer_Dungan]

This isn't the first post about changes to the APIs... I haven't seen any new documentation yet, but I have reached out to someone at Adobe to see if we can get some info for people.

[Gigazelle]

Which API endpoint is this for? Reporting API, Data Warehouse API, or something else?

[Biggsie415]

Reporting.

[ericdemarse]

Similar thread is here: Adobe Analytics API - Adobe Experience League Community - 643303

A few members have surfaced the same issue of having new fields "itemIds" and "values", with "s" on the end. 

@Gigazelle FYI regarding the other thread but I'm assuming you're already aware. 

[ginac001]

I just got this reply on my support ticket:

---

The fix is pushed to prod. Additional fields `itemIds` and `values` are removed from the response in traditional analytics.

---

[BBiggs]

Additional info from support: 

In the future, Adobe may add additional fields to the JSON response in their APIs. Customers should not rely on strict JSON parsing and should be flexible to the presence of new fields in the future.

Well-built (interoperable) JSON parsing and data handling systems are expected to ignore new members that they don't understand and thus new members should be addable to an object without affecting existing members.

In addition, the Report API documentation Reporting API (adobe.com) specifically states, "This guide does not include descriptions for all request and response parameters for the reports endpoint. "

Adobe reserves the right to add additional members to JSON objects and considers the addition of new members to existing objects to be a non-breaking change and thus does not version API methods when new members are added. A breaking change, which would result in versioning of the API methods, would be something like changing the name of a member or deleting or no longer returning a member.

[Jennifer_Dungan]

I agree with this.. processing the response shouldn't be rigid... if a data field was changed that would cause a breakage (actually switching a string to list, etc)...  but adding new fields should roll through (if the process was coded properly).

If you rely on "key in position 1" and "key in position 2", instead of on the key names, this can cause issues because new fields may filter into those positions unexpectedly.

[ginac001]

I don't disagree with the thought that a well-built system should be able to reject the additional fields; I actually changed my process to do just that as protection in the future and it is a much better solution than what I had. 

However, I am disappointed by Adobe's response above.  Maybe I'm just more sensitive to the tone the statement that "Adobe reserves the right...." than others here; but it feels like a mistake on their end is being blamed on those of us who had issues.

[Jennifer_Dungan]

True.. the tone could have been better. Even if these changes had been forewarned.. at least people could have prepared for a potential situation, instead of being hit out of the blue with an issue that you had to investigate to even figure out what broke.

This is definitely not a blame game, this was a real problem and while it may have spurred better code to prevent future issues, this would have been an unscheduled hot fix for a lot of people to get out quickly to reduce impacts.