Recently, one of the participants in the Bungee Connect early access beta asked me how to view XML information in Bungee Connect. The usual context for needing to view an XML doc is when calling a REST API, so I’ll use that as an example. What follows may not be a complete answer to the developer’s original question, but with a little luck, it provides a solid enough foundation from which a developer can discover tricks. Also, I’ll build from simplest (no Bungee, just a browser) up to most involved (inspecting an XMLDocObject that has been populated from a REST reply).
Start with the Browser
The easiest way to view the XML reply to a REST call is use your browser. For example, take a look at last.fm‘s Audioscrobbler API. The REST API for finding artists similar to Moby would be http://ws.audioscrobbler.com/1.0/artist/Moby/similar.xml. To see the XML for the API, you just enter the URL into the browser’s address bar.
Using HTTP.get in Bungee Connect
The easiest way to make the same call in Bungee Connect is to use the HTTP utility (found under TypeLib: Utility) to call the same URL. To do this, you add a var to a function, setting its type to HTTP, and its default value to Object so that the HTTP var gets instantiated with the function.
Next, you add the call function() command, setting it to call the HTTP var’s get function. The get function has two arguments: an [in] for the URL to call, and an [out] for where to store the result. Assign the latter to a string field, and now you can make a form with a button bound to your function, and a MultilineLabel bound to the response string. When you simulate the form, you get a quick way to see the raw, unformatted XML. It’s not pretty. The ‘<‘ and ‘>’ characters appear in HTML encoding (ampersand-hash-60-semicolon), for example. But it does confirm whether or not your Bungee Logic is retrieving XML for your API call or not.
I hardly ever use this technique, but when I was just getting used to using Bungee Connect, I found it re-assuring to know that I was at least successful at getting XML responses.
Using XMLDocObject.readUrl in Bungee Connect
For most REST calls, you will use the XMLDocObject utility. You do this by creating a var based on the XMLDocObject type (also found under TypeLib: Utility). XMLDocObject has a function called readUrl, which allows you to import the XML directly into an object type designed for storing XML. You use this in much the same way as the HTTP.get function. First you add a var to a function, setting its type to XMLDocObject, and its default value to Object. Next, you add the call function() command, setting it to call the XMLDocObject var’s readUrl function. When executed, the readUrl function will populate the XMLDocObject with the XML response.
The data stored in the XMLDocObject type is constructed like this:
Within the XMLDocObject structure, the XML data is stored in the fields below the root field. You can use these fields to start inspecting the XML data.
For example, to know which XML element was assigned as the root of the response to the audioscrobbler API that we have been using as an example, you can assign XMLDocObject.root.name to a string that displays in a form, or simply use the dialog message command in your function to display the var XMLDocObject.root.name as a browser dialog message. For the audioscrobbler API above, the result is similarartists.
You can also inspect a little deeper into the XMLDocObject using the two collections, attributes and children. Because these are collections, inspecting their exact content is not quite as easy as displaying XMLDocObject.root.name, but you can still get some quick information. All collections have a numItems field, which will tell you the count of items in the collection. Once again using our audioscrobbler API example, you will find that XMLDocObject.root.attributes.numItems equals 4, which is the number of attributes in the similarartists element (artist, streamable, picture, and mbid). Likewise, you will find that XMLDocObject.root.children.numItems equals 100, which is how many artist results come back with each call to audioscrobbler’s similar artists API call.
Wrangling XML Into Objects
Inspecting XML is the first step to making it practical in Bungee Connect. The next step is converting XML into actual data objects. The XMLUtil utility provides an xmlToObject function for just that purpose. If you would like to learn how to use this handy function, check out the tutorial called “REST Easy” in the Bungee Connect Documentation wiki.
One Last Thing
I should also mention that within the next two weeks, we plan to roll out a killer new feature that Bungee engineer Nate Ekstrom has been working on to help in debugging your Bungee Logic: code break points. When that feature hits, BCDN developers will have a much more elegant tool for inspecting XML responses than the tricks I share above. Since the feature is certainly worthy of its own blog post, with screenshots, I’ll save the details until we get the feature rolled out.