topic Re: Error in already fuzzy documentation - and the pain of XML (as always) in Integration and Testing

Error in already fuzzy documentation - and the pain of XML (as always)

winternet — Thu, 13 Nov 2014 15:15:25 GMT

I have tried for a long time now to make a AIM XML createTransactionRequest that at the same time creates a CIM profile based on the transaction. It constantly told me that <payment> was not allowed within <transactionRequest> ! Suddenly I realize that I get different errors depending on the order of elements within <transactionRequest>. The documentation doesn't talk anything about a required order of elements, but when I read the XSD closer I suddenly realize the sequence requirement! Not only does the documentation not mention that the sequence is important, it even lists <profile> and <payment> in the wrong order. <payment> must come before <profile>.

I hope this can save someone from wasting a lot of time - and Authorize.net will correct and improve their documentation.

The documentation is also very fuzzy about the XML structure - what elements need to be created where and how they should be nested. You figure it out eventually but it could be A LOT clearer.

Oh how I wish we could soon get rid of XML and use JSON instead - it is so much better and simpler to deal with. We simply don't need all the complexity XML has.

Re: Error in already fuzzy documentation - and the pain of XML (as always)

RichardH — Thu, 13 Nov 2014 17:21:19 GMT

Hello @winternet

Sorry to see you are having problems and thanks for the feedback. To help our documenation team make improvements, were you using the API Reference or the PDF AIM XML guide?

Richard

Re: Error in already fuzzy documentation - and the pain of XML (as always)

Lilith — Thu, 13 Nov 2014 19:07:45 GMT

We found the issue in Table 6 of http://www.authorize.net/support/AIM_guide_XML.pdf -- and I've already reported the issue to our documentation team. Thank you for reporting this, @winternet !

Re: Error in already fuzzy documentation - and the pain of XML (as always)

winternet — Fri, 14 Nov 2014 07:37:58 GMT

Yes, I only looked at the PDF - I never even thought of looking at http://developer.authorize.net/api/reference/ since I was assuming it to be the same. But I see now that it is much more clear and even has the correct order. It is still not clear that the order of elements in important though - and I think that will confuse many since there is no apparent reason (if any at all) for elements to be in a certain order. If error message clearly had said "The order of elements is wrong" it would have been okay, but the error message is simply "The element <payment> is not a valid child element of <transactionRequest>" and you are totally confused because you know it is a valid element! So please make that very clear on the page - or even better, change the XSD to not have that requirement!

Thanks for getting the issues fixed!

Re: Error in already fuzzy documentation - and the pain of XML (as always)

Lilith — Fri, 14 Nov 2014 23:00:16 GMT

You're welcome! The new API Reference Guide is the direction we're going for all API documentation, exactly because it's much clearer than our old PDF documents.

By the way, you may want to check the API Reference Guide again sometime this weekend--you should see a pleasant surprise.