Bruce Eckel, in "Are Web Services Real?
," points out the next hurdle for web services, in terms of not just documenting the APIs, but actually pointing out how they're used.
Part of this may be the proliferation of web service APIs: in Java alone, there are many ways of issuing a web service call (or servicing external web service requests): Axis and Axis2, GLUE, JAX-WS and libraries implementing it, and this doesn't even begin to address using other languages to manage web services, with each language having their own ways of using web services and the protocols surrounding them.
Fast-forward to today, when I'm working on creating a site that will deliver a physical product. I think "perhaps I can just quickly bash something together to query the Fedex site using Web Services." Not only had I heard that Fedex has Web Services, just about every book and article gives Fedex as an example.
You can find information about Web Services on the Fedex Site. But the docs are not very clear about how to make an actual call, and I couldn't find any examples. Apparently there's a single C function that you can call with arguments representing your call, but when you look at the document for this, called "FedEx API Client Libraries Developer’s Guide", it's two pages long and incredibly vague -- and this is supposed to be the simple solution. The purpose of the function is "To connect to ATOM and send a FedExAPI transaction to the FedEx Internet Server," which makes it sound like ATOM is somewhere else, but the first argument to the C function is "the host name or IP address of your system that is running ATOM." Nowhere in the document does it say what ATOM is.
This problem might be expanded to consider W3C APIs like WS-Transaction, WS-Security, and other similar WS-* mechanisms, all of which have their place, but require a commitment to understand. Theories of learning indicate that one of the fastest ways to teach someone something is by offering a system in which the behaviours of a system
are visible, but web services may be too complex for this to work.
...after an hour or so of hunting, I didn't find any real examples of using the Fedex Web Services API with, for example, Java, which they included as one of the supported languages. I did come across several products that said they provided this functionality, but the one that I looked at required me to say what application it would be used with -- like, Outlook or Quickbooks, which made me wonder if I had misunderstood something.
Just to be clear, I'm imagining that the average user of Fedex Web Services will have, like me, a product and they know the weight and the dimensions of the shipping box. They know where it's shipping from, and they'd like to put in a Zip code for the destination and find out how much it will cost to send it ground, priority, standard and 2-day. Now that seems like, if Web Services are so great, it ought to be something one could bang out in a couple of lines of code, and voila, instant calculation of shipping costs! But if Web Services aren't real, then clues could be incomprehensible docs like the one mentioned above (if people were actually using it then someone would complain and they would fix the docs) and if you google for examples you don't find any.
What do you think? There are multiple Java APIs that have this sort of unfortunate "black box" approach, but web services abstracts that away from Java to become a language-neutral problem. Even REST
- a simpler API than what many consider "traditional web services" - has the problem of clear documentation of process. While Mr. Eckel outlines a solution en passant
("if people were actually using it..."), is there a "grand solution" hiding somewhere?