Discussions

News: Next Hurdle for Web Services: Documentation?

  1. 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?
  2. its even more worse...[ Go to top ]

    Ok, its quite unbelivable how bad documented the FedEx service is, but on the other hand, many logistic companies like DHL doesnt offer webservice at all, which is in fact ridiculous because tasks like Track&Trace really cry for a webservice implementation. I am implementing data interchange processes for many logistic providers and what i see on a daily basis is really beyong imagination. Sometimes i have the feeling that the IT staff on these sites live in 1980.
  3. First, the FedEx service doco does reek. A five minute glance reveals no info on web service calls that I can make (whether SOAP, REST, etc.). But Bruce seems to miss the point a little...make a C method call to do a web service? Why not find the WSDL and use a tool like eclipse WTP to test it, then XFire or some other simple Java API to call it? (Not withstanding that FedEx does not seem to have any WSDL lying around, but I did find very detailed documentation on XML request schema, their FedEx Shipper Direct stuff). He is also treating WS as a silver bullet. WS is not going to make your life any easier. It has its own domain and set of problems to go with it. Get over it. But it is a tool that lets me call a service without caring what that service is implemented in (C or otherwise).
  4. WS is not going to make your life any easier. It has its own domain and set of problems to go with it. Get over it.
    LOL What is the point of WS then?
    But it is a tool that lets me call a service without caring what that service is implemented in (C or otherwise).
    Have you ever heard of CORBA, ICE, Hessian?
  5. He is also treating WS as a silver bullet. WS is not going to make your life any easier. It has its own domain and set of problems to go with it. Get over it. But it is a tool that lets me call a service without caring what that service is implemented in (C or otherwise).
    I remember using something like that once, I think they called it CORBA :^) Isn't strange the way we spend all our time going around and around in small circles. I guess I just don't get it either. Paul.
  6. From my perspective, implementing standards, with out clear documentations may have many ‘business secrets’ behind it. For example, many of the available standards' API implementations will be a trail in the market, for which the highly inspired technical people in the IT world can become a volunteered 'testers'. If those trail runs become hit in the market, it makes sense to release those APIs for general public usage with updated documentation rather than draft documentation for public usage from the start. I do not know how many people agree with my comments.
  7. If he wants to see examples of Web Services that are documented well, he should check out the Salesforce.com APIs. I wish every company's integration points were as accessible and well-documented.
  8. Semantics[ Go to top ]

    The issue is specifying semantics of the service. Clearly, WSDL and schemas don't (rightly so) convey the semantics of the service, and what is needed a clear documentation of semantics of messages consumed/generated by the service. I don't think this is a problem with web services. Every interface/service (wether using web services or not) needs a description of the semantics so that is can be used correctly.
  9. Re: Semantics[ Go to top ]

    I would say that if API (and code) is well written then in 90% cases it is all the documentation we need to start using it.
    Clearly, WSDL and schemas don't (rightly so) convey the semantics of the service,
    What documentation would you need if you see function like this: A: CostTimePairs[] estimateShipment( Dimensions d, Weight w, Place from, Place to ); Now compare with: B:Object[] calcShipm( int a, int b, int c, float w, String from1, String from2, String to1, String to2 ); IMO in case of #A we do not need _any_ documentation at all if Dimension and Weight classes are well written to and have enums defining units for the numbers{meters, inches}, {pounds, kilograms}, and {USD, CAD,...} #B requires a lot of documentation and still very cumbersome to use
  10. Re: Semantics[ Go to top ]

    I would say that if API (and code) is well written then in 90% cases it is all the documentation we need to start using it.

    Clearly, WSDL and schemas don't (rightly so) convey the semantics of the service,

    What documentation would you need if you see function like this:
    A: CostTimePairs[] estimateShipment( Dimensions d, Weight w, Place from, Place to );

    Now compare with:
    B:Object[] calcShipm( int a, int b, int c, float w, String from1, String from2, String to1, String to2 );

    IMO in case of #A we do not need _any_ documentation at all if Dimension and Weight classes are well written to and have enums defining units for the numbers{meters, inches}, {pounds, kilograms}, and {USD, CAD,...}

    #B requires a lot of documentation and still very cumbersome to use
    That's precisely the point. The first example conveys the meaning to an english speaking programmer. It ends there. As the service author, you still need to specify what it means to send a Weight of 1 zillion pounds, or what is supposed to happen when Dimesnions are unknown. These won't be as obvious when you consider more complex messages, and can only be clarified with a specification of semantics. Not doing so would be problemantic in the long run.
  11. I'm not sure I understand Bruce's complaint in this case. He makes an example of a four page document describing a single C function, but there is also a 272 page document with a very detailed documentation of the XML API, including examples of messages, etc (http://fedex.com/us/solutions/wis/pdf/fedexapioverview.pdf?link=4). Sure, they can be criticised for not documenting how to send XML messages according to this API from various popular programming languages. It'd be smart if they did that, just as others do (google, Amazon, Salesforce). On the other hand I think Bruce and most other developers know how to send an XML message to an http server.