Over the past year or so, I have been working on a project which involves interfacing with several different groups from my JEE application. I recall a day when interfaces were required to provide detailed documentation containing file or message specifications, formatting information, response timings and volume information, and so on. Something has fundamentally changed over the years and it is not for the better!
First of all, if an interface partner requests formatting and connectivity information, should this not be already existing in a document repository to be provided on-demand? It is amazing how many times over the past year I had to reverse-engineer information because the provider groups had not documented them! The process became more a matter of dependence on experience, reading tea leaves, and collecting old-wives’ tales in order to make heads or tails of the interfaces’ own data. Incredible as it may seem in this day and age where umpteen tools exist to permit developers and architects to lay out their public interfacing data.
Hand-in-hand with this are those interfaces that provided specifications but then did not follow them! In some respects, not having any documentation is better than having misleading documentation. Kind of reminds me of Mark Twain’s adage about a broken clock being right twice a day versus a clock that is slow or fast! Can you believe that in one case, I was provided a slew of XSDs for XML responses over MQ that I coded against and when I started testing against the interface, one of the messages had a blatantly misspelled top-level tag? How in the world did that get through their testing phases without being fixed or at least correcting the XSD to the misspelling for future interface partners? By the way, the product is in production so it can’t be changed now! Incredible….
In another case with an interface that exposes a webservice, I ran into problems using Oracle JAX-WS consuming their data. After examining their WSDL which boldly indicated in the xs:schema statement that elementFormDefault is unqualified, their returned data qualified some of their tags with namespaces and others were indeed unqualified. JAX-WS took (correct, in my opinion) the rigid road and failed to decode any of their tags since they did not meet the specs. When I brought this up to the interface partner, they agreed that they are violating the spec but they can’t change it now since they are in production! Again, how was this tested in the first place? I ended up having to code this functionality using Apache Axis 2 which seems to ignore the WSDL’s requirement.
The number of interface partners who could not explicitly provide the format for their data was mind-boggling. If you are responsible for data delivery, should you not KNOW your data? How in the world do you resolve problems with your interface consumers – if they have an error consuming your data, did you format it incorrectly or is it something on their side. I had one battle with an interface partner because they made a subtle change on their side which skewed a section of their fixed-length fields. They insisted that they were correct until I was able to show them their historical data was aligned differently. After our heated battle, they admitted their problem and fixed it. Again, how in the world could they test their changes without proper specifications for their QA team to follow?
How about dates and datetime objects? In international operations like most of us work for, how many interface partners explicitly provide normalized date information? It baffles the mind how many interfaces provide a raw date object (e.g. 20120122) without timezone information. This is bad enough but when one goes back to the interface partner to ask what timezone this date corresponds to, they throw up their hands and say, “I don’t know!” If I had my druthers, every date/datetime object would be transmitted with timezone information and if this were not possible then it would be centered on UTC. I have partners that transmit dates from multiple timezones as singular blobs of data devoid of timezone indicators. Oh joy!
When an interface partner provides a comprehensive document one would expect that it is accurate and can be coded against. While in many cases this is true, I did run into one which indicated that their data travels through MQ as XML. They provided documentation with the XSD of the XML and several examples. When I took my code to test, it failed immediately. Why? Unlike the document which indicated through its examples that the XML traveled the wire raw, the XML actually had an <?xml…> header.
Finally, what about your downstream partners? When you provide proper documentation defining every aspect of the interface that you expose for them, you would expect them to follow this. Not so. I had the glorious moment of having a critical defect opened against my code because it was not providing the data with a proper high level tag. After I scrounged up the specification, I discovered I was sending the correct data in a proper format — the downstream application had ignored the topmost tag in their code! Which brings me full-circle….
Have folks gotten sloppy with developing interface documentation because they figure that nobody will follow it anyway? Hopefully this is not the case. My appeal is to all Project Managers and Team Leads out there — do not let this critical discipline fall by the wayside. If you are in-charge of an application that exposes interfaces, ensure that this public contract is properly documented and tested against anytime changes occur within your application. Without it, interface consumers merely are programming by guesswork which is not a good thing in the long run.
