Setting up for using the Reporting API

The recent article on how to set up a test platform was a success, so I have decided to listen to a suggestion by Mitchell and write a similar article about enabling your friendly marketer to play with the Reporting API.

There are a couple of ways she could achieve this.

API Explorer

This is the easiest and fastest way, and she doesn’t even have to install anything!

Just go to https://marketing.adobe.com/developer/api-explorer. It is a very good idea to log in, because that way the system can automatically populate the Username and Secret boxes for you.

Once logged in, select your API (e.g. “Report”) and a method (e.g. “Queue”). The system will populate the text box underneath with an empty ReportDescription structure.

You now need to put your parameters into that structure, then you can hit the “Get Response” button at the bottom.

Check out my earlier article on using the Reporting API for screenshots.

I highly recommend using the API Explorer first!

Pro-tip: always have two tabs open. Use the left one for requests and the right one for pulling the results. That way you can tune your request without having to copy&paste like a lunatic.

PHP

If your friendly marketer is someone who considers using the Reporting API, chances are she has a local web server on her machine, something like MAMP or XAMPP.

In this case, it might make sense for her to build web pages that show results of her custom Reporting API queries, and what better to use than PHP in that case?

The great thing about using PHP is that a lot of the examples on the Developer site are in PHP. That should make starting to use the API pretty easy.

And there is, in fact, no need to set up anything else!

As a first step into running code against the Reporting API, I would probably copy some sample code into a file called test.php and access that file.

What’s great with PHP is who immediate the feedback is. Edit the file, reload in browser, that’s it.

What’s difficult with PHP is that for “casual development”, debugging is not a natural part of the flow, and you end up with a lot of print_r statements in your code. But hey, who cares?

Java

Maybe your friendly marketer is a developer at heart. Maybe she used to be a coder, or maybe she just taught herself Java, because why not.

In the past, I have written about first steps in Java, so I shall not repeat myself here.

My guess would be that Java is overkill, but if you or your friendly marketer like a nicely contained environment, in which everything happens within the IDE, then it might be the best choice.

All you need, really, is a JDK, an IDE like eclipse or IntelliJ, and a couple of libraries.

And it has become much easier to access the Reporting API in Java since it is available as a REST endpoint. SOAP used to be a bit tedious…

C#

Yeah, ha ha, not going to go there.

Javascript

I have also written about accessing the Reporting API with Javascript in the past.

Accessing the Reporting API in Javascript is sort of like cutting out the middle man. All you need is an editor and a browser.

Python

Oh, I’m on very thin ice now! I know nothing about python!

But a lot of people like the language, and it is supposed to be very easy, so maybe it should be on this list.

In terms of setup, you’re done if you’re on a Mac. On Windows, it is fairly easy to install Python. Just get the installer from www.python.org. I told the installer to add python to the PATH, and I installed it in c:\dev\Python3.5 rather than c:\Program Files\Python3.5 (because that way updates would work).

Actually querying the API does actually look pretty simple in Python:

# generates the header for WSSE rest authentication
def generate_xwsse_header(user_name, user_secret):
    timestamp = datetime.utcnow().isoformat()[:-4] + 'Z'  # adobe rest api uses the Z annotation
    nonce = str(uuid4())
    password_digest = sha1((nonce + timestamp + user_secret).encode('utf8')).digest()
    password_digest_base64 = str(base64.encodebytes(password_digest), 'utf8').rstrip()
    nonce_base64 = str(base64.encodebytes(nonce.encode('utf8')), 'utf8').rstrip()
    return {'X-WSSE': 'UsernameToken Username="%s", PasswordDigest="%s", Nonce="%s", Created="%s"' %
                      (user_name, password_digest_base64, nonce_base64, timestamp)}


# get the report data
def get_report_data(user_name, user_secret, report_description, data_callback):
    initial_req = request.Request('https://api.omniture.com/admin/1.4/rest/?method=Report.Queue',
                                  json.dumps(report_description).encode('utf8'),
                                  generate_xwsse_header(user_name, user_secret))
    with request.urlopen(initial_req) as initial_response:
        data = json.loads(str(initial_response.read(), 'utf8'))
        report_req = request.Request('https://api.omniture.com/admin/1.4/rest/?method=Report.Get',
                                     json.dumps({"reportID": data['reportID']}).encode('utf8'),
                                     generate_xwsse_header(user_name, user_secret))
        with request.urlopen(report_req) as report_response:
            data_callback(json.loads(str(report_response.read(), 'utf8')))

And yes, that code could be improved. But it shows how straight-forward Python can be.

Others

Believe it or not, you can use the Reporting API from Excel!

Ok, that’s slightly misleading. “Using the Reporting API from Excel” actually means using Report Builder.

It’s like asking “how about using the Reporting API in a browser?” which would refer, of course, to the Reports in Analytics itself, or to the pretty cool Analysis Workspace.

But how about R?

There’s a package for R that can pull data straight out of the Reporting API, written by Randy Zwitch.

Very useful if R is your thing.

Since I know nothing about R, that’s about the extent of things I can say. I hope that I will have time one day to write about it a bit more…

Which one?

Which one of those would I recommend?

PHP is probably the easiest to handle, and it is very forgiving as a language, meaning you get away with pretty much anything. Good for beginners, bad for the programming style they’ll acquire. A big pro are all the samples on the developer portal.

Java seems to me the most integrated choice, but it comes with a steeper learning curve.

Javascript, described by my office mate Senol Tas as the language that makes Java’s “write once, run anywhere” promise reality for the first time, is as quick and dirty as PHP, and you don’t need a server. You currently won’t find as much sample code as for PHP.

I am not sure about Python, simply for the reason that I do not trust a language if I have to close it’s shell with a function call (exit()) or an absurd key combination (CTRL-Z+ENTER).

R, on the other hand, is your perfect language for this use case, as long as you have a couple of PhDs. I guess if you’re aiming for that well-paid big data analyst post, this is where you want to start.