WSDL is not documentation!

This post is more than 2 years old.

Rant Mode On...

Maybe I'm not smart enough - but it really bugs me to download docs and see this in terms of the API:

Include as much detail as possible about your shipment. The RateService WSDL provides elements to identify your shipment, including shipping option elements. This information is important for calculating the correct shipping costs with surcharges.

Well, yeah, sure, the WSDL can tell you how to form your request, but, um, would a table of details have hurt you? This is almost as nice as the Google APIs. I won't say where I found this, but you can probably guess by the quote. Of course, now that I've blogged this, someone will point out to me where the docs are.

Rant Mode Off.

Raymond Camden's Picture

About Raymond Camden

Raymond is a senior developer evangelist for Adobe. He focuses on document services, JavaScript, and enterprise cat demos. If you like this article, please consider visiting my Amazon Wishlist or donating via PayPal to show your support. You can even buy me a coffee!

Lafayette, LA https://www.raymondcamden.com

Archived Comments

Comment 1 by Joshua Curtiss posted on 10/22/2007 at 9:45 PM

AMEN.

Comment 2 by Charlie Arehart posted on 10/22/2007 at 10:02 PM

Ray, I want to make sure I understand your question/concern. Are you saying that the only you info you have is some document with that phrase, saying to look at the WSDL to find out its available methods and expected arguments?

Well, the good news is that while you may not want to parse apart the native XML, fortunately there are tools that will do that job for you.

For instance, for those not using DW (more below), there are web-based interfaces like http://xmethods.net/ve2/Too... and http://www.mindreef.net/tid... (though the latter is responding poorly today for some reason, but I used it just last week.)

Those using Dreamweaver should note that ittoo has a nice built-in feature to do that sort of web service browsing, and more. Many miss it (and some use it as one of the few reasons they fire up DW).

If you've ever used the CFC browser feature, it works the same and is in the same place, on the Application panel, in the "components" tab, where you select "web services" from the drop down. Then you can point it at any WSDL URL. It will report all the methods and their arguments. Even better, if you drag a method onto the code window, it will build a CFINVOKE to call it.

Sadly, as far as I could tell, neither CFEclipse nor the Adobe Eclipse plugins seem to offer that for Eclipse, but I'm sure some other tool does, and someone will tell us.

I did a talk on all this at last year's CFUnited, for anyone interested in more on "web services tricks and tips" in CFML, the PDF of the slides (lots of detail) is at http://carehart.org/present....

Finally, Ray, if this isn't what you were looking for and you already knew already knew all this, I hope it will help others who may come along and read it.

Comment 3 by Raymond Camden posted on 10/22/2007 at 10:07 PM

Well, my main point was to gripe about the docs. I know there are tools that can parse WSDL, but why isn't... the company who shall remain nameless... providing decent docs?

Comment 4 by Raymond Camden posted on 10/22/2007 at 10:09 PM

Hey Charlie - I can't pick Web Services from the drop down. If I remember right, this feature didn't ship with the Mac DW.

Comment 5 by Jason posted on 10/22/2007 at 10:35 PM

The adobe plug-in does offer web service browsing. Just open the "Services Browser" view, then next to the minimize button on that tab click the little "server with the world". You can then add WSDL locations and view the methods etc. Of course insert the cfinvoke /createobject code as well.

Comment 6 by Raymond Camden posted on 10/22/2007 at 10:40 PM

Interesting. I never knew about that. Thanks. But I'm not sure it is complete. For the WSDL I'm looking at there are things in there I'm not seeing via the Services Browser.

Comment 7 by Charlie Arehart posted on 10/22/2007 at 11:08 PM

@Ray, I don't use DW on the Mac so I'm afraid I can't say if the option is there. Anyone else know? Follow the instructions above and let us know if you see web services as an available option. (I can't see why it would be Windows-specific, but stranger things have happened.)

@Jason, thanks very much for the pointer to the WS browser in the Services browser. I'd just missed it (since it's so far off to the right). So that's a world icon, eh? Too small at my monitor's resolution to perceive that. :-)

As for the creation of invocation code, I'll clarify for other newcomers to it that it's not a drag and drop operation as in DW, but rather you right-click either on the WS name (parent object in the tree) or on a method name. It's nice that it supports more than just the CFINVOKE DW does: CFOBJECT and createObject on the WS name, CFInvoke and createobject on a method name.

Finally, Ray, as for it not showing the methods you expect, I guess we won't be able to confirm that unless you spill the beans on the WSDL URL. :-) But maybe someone with familiarity with the Adobe Eclipse Services Browser can chime in with any known limitations.

Comment 8 by Theo posted on 10/27/2007 at 8:46 PM

And API documentation is not documentation.

http://blog.iconara.net/200...