All New Reporting API

The Maintenance Release of the Adobe Marketing Cloud on February 20 saw a lot of changes, fixes and new functionality.

Personally, I am rather chuffed about the new Reporting API 1.4! Here is the excerpt from the release notes with the high level list of changes:

• OAuth Authentication
• Pathing support (Next/Previous Page, Next/Previous Page Flow, Path Finder, Fallout)
• Enhanced permissions
• Robust error reporting with more descriptive messages.
• Additional enhancements, including simplified report definitions, and better consistency across the API.
• Smarter defaults to make it easier to get started.
• Major rework of many of the method to make them easier to use.
• Hundreds of bug fixes.

How does that sound? OAuth? No more Nonce? More descriptive error messages? Smarter defaults? Makes me happy!

The notes state that version 1.2 of the Reporting API will be deprecated at some point. What that means is that your WSDL (for SOAP) or endpoint (for REST) will have to be updated to either v1.3 or v1.4 before “early 2015”.

You will also likely have to update your code a bit (if you go to 1.3), or you could decide to go straight to 1.4 and use all it has to offer.

Let’s look at a couple of examples.

Authentication

With versions up to v1.3 of the APIs, the authentication was done via username, secret and nonce. There were libraries for that sort of authentication for some systems (I’ve been using it with Java successfully), but not all (C# was difficult).

Now you can build tools that allow users to authenticate using OAuth 2.0, which is basically what most modern web services use to allow third parties access to some of the data or functionality.

An example is when you add an app to twitter. The app will pop upon a window in which twitter asks you whether you want to allow that app to access your data. If you click ok, the app and twitter will exchange a token, granting the app access to the data it needs.

There is some pretty exhaustive documentation on the Developer Portal about this so I won’t go into details here.

Let’s just mention that currently, you can use Authorization Code Grant and Implicit Grant. In the future, you’ll also have Client Credentials Grant.

For the users, this means they no longer have to look up their “secret” in the Admin Tools. And they don’t have to remember yet one more login.

Pathing and Fallouts

Yes! You can now pull pathing reports and fallouts via the Reporting API!

I have often been asked whether there was a way of pulling these. Most people were thinking about some sort of display for “what is currently the page with the most exits?” or “from where did people go to the home page?” or “what do people do after the thank you page?”.

All of this can now be done via the Reporting API, so there is nothing stopping you now from building an all-encompassing, incredibly useful and painfully beautiful dashboard. World domination is within reach!

Seriously: there are so many different Adobe customers around. I always wonder why there currently is no real ecosystem around the APIs. This is a proper opportunity! Build some cool dashboards or apps!

Back to pathing: the documentation has a lot of easy examples and shows you what to expect in return.

Error Messages

This one is bigger than it sounds. The Reporting API is now much more explicit when it comes to reporting errors. In some cases, it now does return errors when formerly it would just have replied with an empty data set.

Peace of mind for developers.

I am not going into the debate strongly versus dynamically typed languages, but I think in our world, strict error checking definitely helps. This is mostly due to the fact that the average developer has never heard of Adobe Analytics before and needs the immediate feedback.

The list of errors is now of a respectable length. There are even lists of element and metric combinations that are valid or not.

I love the system_failure error, especially because the term “failure” is defined as “The system has failed and it’s not the users fault.”

Others

A couple of metrics and elements were added, some were removed.

Some of the parameters of the report description now have meaningful defaults: metrics default to “pageviews” and if you specify no date(s), the system will return data for the current day.

The report description will now immediately be parsed and validated, so if you did something wrong, the system will let you now then and there.

Permissions will now be enforced. Users who in Adobe Analytics do not have access to certain metrics or elements will not be able to see those in the Reporting API 1.4 either.

A really important step forward in the same direction is that elements now are explicitly restricted on what elements they can be used with.

Where before you could queue a report that used a traffic element along with a conversion element (which would lead to an empty report, because Adobe Analytics cannot do that), you will now get an error.

And you can use the GetElements method to figure out what the valid breakdowns are for a given element.

This can be used during development to keep you sane, but it can also be used in your application to provide a drop down of possible breakdowns in a UI that allows users to select their elements.

All in all, the new Reporting API is a very nice improvement. Go use it! Make apps!