Mashup Guide

For the second draft of Chapters 6 and 7, I've been writing up a section on working with SOAP. I knew that it might be complicated to explain but I had no idea that it would be so difficult to distill the subject down to clear rules of thumbs that really work. I need to give up right now on trying to figure out all the kinks -- of which there are many -- in consuming SOAP services from a variety of languages. I've made a lot of progress but that work has been really slow-going and extremely frustrating. More to the point, the contribution that a section on SOAP/WSDL makes towards finishing the book are insufficient to justify the immense amount of effort I have to expend on the topic.

I've come to some basic conclusions about SOAP and WSDL. A fundamental problem with tightly coupled exchange protocols such as SOAP is that there too many places where errors can be made. And when you run into problems, It's hard to even know where the error are. And the protocols are pretty complicated. Underlying complexity wouldn't matter if everything just worked. But that's the case right now, forcing people who want to consume SOAP services to dive down into the details of the protocol. It seems that it's been difficult for people to write and interpret the protocol properly. Or people in scripting community have generally thought it not worth the effort to do so. SOAP+WSDL are very fragile technology

Ideally, you wouldn't have to know much about how the underlying technology works. But the documentation of SOAP libraries is often bad. You are not told what certain parameters mean. That means you need to know about how SOAP works to make sense of the parameters. That really shouldn't have to be the case. Moreover, there is more coupling between the conceptual models of SOAP and WSDL than one would know. So much easier to get started with REST, even if REST has a lot of subtleties of its own.

Comments anyone? I'd really like to be shown where my thinking is wrong and how I can start using SOAP and WSDL with ease in PHP, Python, etc.

I just posted my first draft of Chapter 6 ("Learning XML Web services APIs through Flickr").

Chapter 6 is a large and complex chapter that aims to do quite a few things. (The current draft runs 34 pages.) I'm excited about chapter 6 because with some refinement, I think the chapter will be able to pull off these goals. By working through this chapter, I want users to have a pretty solid understanding of the capabilities of the Flickr API and basic PHP programming and a conceptual foundation for HTTP and HTML and web services.

The overall structure is almost completely in place. I will say that I need to provide a fair amount more explanatory prose. I was striving for conceptual and technical completeness. I will balance it out with more descriptive prose in the next pass.

There is a tension of how much PHP hand-holding do I want to provide. I still have in mind an audience like my students who by and large are not programmers but who can be led into a nice programming example without having them learn all the grammar of PHP up front. This is the approach I take here.

Major changes that I still want to make the chapter really complete:

• I'd like to expand the section on the Flickr API Explorer. Users can learn a lot from using it. I would like to write a lot more about how to use it. There are a lot of things to do to improve this section, which I think is a key section of this chapter and of the book: 1) explain why the Flickr API explorer is so cool 2) show its full capability 3) do gets and then set-type operations 4) make some more exercises that challenge the reader to really understand the API of Flickr 5) explain the differences in how you can call the various methods. 6) Use this as a way to explore the capability of Flickr. 6) Include screen-shots.
• I'd like to weave in explanations of server vs client-side programming, HTML vs XML, and CSS. By the end of the chapter, I want to have my readers go through a core of PHP programming that covers pretty extensive use of the Flickr API. No database yet. No JavaScript yet.
• I'd like to put in a section on CSS to get that into the mix. I didn't do that because I will admit that I've not put a lot of emphasis on styling myself -- but it would be useful to discuss CSS.
• It would be great to be able to come through and add Java/.Net/Ruby/Python code snippets to do all the same things once the entire book is ready to go with PHP....
• I'd like to explain Flickr uploading to not only complete out an explanation of the tricky bits of the Flickr API but also to illustrate the use of POST in PHP and HTTP headers.