If you’ve been paying attention, you will have noticed that I recently published a series of articles over on phparch.com discussing the new Data Connection Wizard for PHP that Adobe has built into Flash Builder 4. While I am not a great fan of Wizards in general, I recognize that there is a segment of the developer population that does like them so I respect that and try not to run screaming from the room every time I see someone using one.
My opinion on them is the same as my opinion on IDEs with code completion and tools like Dreamweaver. If you can write the code in Notepad.exe and are just using the Wizard as a convenience, fine. However, if the Wizard spits out code you don’t understand, stop using it now, start writing your code by hand and come talk to me when you understand the magic behind it.
That having been said, I do understand the code that Flash Builder 4’s Data Connection Wizard spits out and for the most part, think that the PHP connection wizard has some limited usefulness to professional PHP developers.
Recently however, I started playing with the Connection Wizard that assists developers in connecting to HTTP services. There are still a lot of rough edges that need to be worked on but all in all, I think this one is much more usable.
The Data Connection Wizard in Flash Builder 4 attempts to solve the problem of how complex a process it is to connect an application to a data service, figure out what is coming back from that service and write the code necessary to actually use the return values. Taken from that 50,000 foot viewpoint it is a laudable goal. However, as will all problems, the devil is in the details. As we saw when working with the PHP Data Connection Wizard, you have to do things like install Zend Framework and put everything in your web root for Flash Builder 4 to be able to do it’s inspection.
An alternative and sometimes solution
Flash Builder 4’s HTTP Data Connection Wizard is a help though. It gives developers a good starting point from which to work. As with the PHP Data Connection Wizard, it attempts to inspect the return value that the API gives and help you use it in your applications. However, unlike the PHP Data Connection Wizard, the HTTP does not require your code to inspect. Instead it tried to make some assumptions based on the inputs you provide and the outputs returned. The results, while not as accurate as the PHP Data Connection Wizard, are still a good starting point.
Today’s shiny, Recipe Puppy
Of course to test this you have to have an API to play with. A quick visit to my old friend Programmable Web turned up a new API that, while not altogether useful in the grand scheme of things, is perfect for our little experiment. Recipe Puppy. Recipe Puppy has 2 things that I really like in an API.
- No Authorization required
- REST(ish) interface
(I qualify this one with (ish) because I’ve made the mistake before of calling an API REST and it not being really REST but really JSON over HTTP. Some people take offense when you dilute the term REST like that so I go with RESTish.
Now that we have an API, let’s build something simple around it. Since Recipe Puppy is an ingredients based search engine, let’s whip up a quick AIR app that will let us search it, pull back the results and display them in a grid. Simple enough and standard fare for API developers. (I chose AIR applications for my demos because then we don’t have to worry about any cross-domain issues.)
Defining the API
First, let’s select the HTTP Data Connection Wizard to set things up. At the bottom of the Flash Perspective of Flash Builder 4, you will see the Data Services tab. Clicking on that will give you a link titled “Connect to Data Services”. When you click on that link it will bring up a dialog similar to Figure 1. This dialog will allow you to select the HTTP Data Connection Wizard from among the other options.
Once you have selected the type of service as HTTP, the Data Connection Wizard will allow you to enter the URL and parameters of this particular API. Recipe Puppy is a very simple API so we don’t have to do much. Here is a screen shot of the finished screen ready to go.
The three important things to enter on this screen are:
- The URL for the API sans any input parameters
- The list of the input parameters. I’ve only listed two because I won’t be bothering with paginating the results
- the name of the service. You have to give it a name. I was very uncreative and named it recipePuppy, feel free to be more creative
One other thing of note, at this point you do have the option of giving each operation a name. We only have one operation with Recipe Puppy but other APIs could easily have many. The default name is operation1, operation2, etc. In the case of Recipe Puppy, I named the operation fetchRecipes. You can name yours whatever you like but when working with real world code, I recommend meaningful names for your operations.
Once you have completed this, you should see that your Data Services tab has changed to something that looks like this.
Notice how your operation name and the parameters you specified are now visible to you. The only problem is, Flash Builder 4 doesn’t know what to expect back from Recipe Puppy because it can’t do introspection like it could with the PHP Data Connection Wizard. We need to help it along a bit.
One final note here. I did leave one important parameter of the API off but I did so on purpose. You can access the screen above where you defined the operations and parameters by right clicking on “fetchRecipies” and then clicking on ‘Properties’. Do this and add a string parameter to fetchRecipies named format.
Defining the return value
Now that we have defined the API, let’s help Flash Builder understand what the API will be returning to us. Right-clicking on fetchRecipes and then clicking on “Configure Return Type” will let us tell Flash Builder what it needs to know to figure out the return value.
The first screen we are presented with just allows us to specify that we want Flash Builder 4 do do the work by “Auto-detecting the return type from sample data”. If you were working with a more complex API, you could also specify the authentication parameters here as well or tell Flash Builder 4 to use an existing data type. We will leave auto-detect selected and move to the next screen.
The next screen we are presented with is where we enter values for the parameters we created. As you can see here, I’ve filled in “i” with the ingredients I have handy; vodka and an orange. I’ve filled in “q” – the general query – with “drink” t limit my return results to drinks. (I’m not in the mood for Vodka ice-pops) and for format I’ve chosen XML.
Click “Next” on this screen actually makes a call to Recipe Puppy, fetches the return value and then attempts to figure out what came back. Because it is XML, it was pretty easy for Flash Builder 4 to figure it out and this next screen shows us what it thinks it found.
Note that the box on the “results” line is checked as an array. If you look at the XML returned by Recipe Puppy you will see that. Flash Builder 4 realizes that in most cases, if there is an array returned, we are going to display, process or iterate through it. So it marks it but allows us to double check it’s work.
Similar to when we defined the fetchRecipes operation, we are allowed to define the name of the data type that is our return variable. I’ll name mine “Recipes”. Once you name it and click Finish, you will see that the fetchRecipes method now returns Recipes. That makes more sense than “Object” but more importantly, Flash Builder 4 now knows what a Recipe is.
…and the rest
If you have read my other posts on the Flash Builder 4 PHP Data Connection Wizard, the rest of the application should be a breeze to put together. I won’t pad my word count by listing the code here. The basic steps are as follows:
- Add a grid in and attach it to your new Data Service
- Add a input field for the Query (Q)
- Add a input field for the ingredients
- Add a “Whoopie button” that calls the search with the query and the ingredients
Here is what mine looks like, I am sure you can do better.
Here’s the catch. The Data Connection Wizard builds a class in the background, actually it builds 2, one that you are not supposed to edit because it is generated code, and a child of that class that you can edit. As part of the process, it creates properties in this class for all the return values. This means if you have a property in your return value names “protected’ (as does twitter), Flash Builder 4 is going to try and create a property of this new class named “protected”. Since the word protected is…protected as a keyword, this will, of course fail. If you are lucky like me and have a friend who already knew this, you may not spend hours trying to figure out why your code is not working. On the other hand, if your friend is like mine, he’ll let you suffer a little before telling you the answer. :)
Be careful of this little gotcha when using the the Data Connection Wizard.
Until next time,
I <3 |<