Flutterby™! : Walls of Shame 2012-02-14 21:32:27.33991+00

Walls of Shame

2012-02-14 21:32:27.33991+00 by meuon 6 comments

Summary of an actual conversation with a developer INSIDE the credit card gateway company. The only one available for this country/currency and customer.

me: Should I send it as: CreditCardNumber, CreditcardNumber or CredicardNumber ? Your documentation and example code has it multiple ways.

Juan: How does it get returned in the error message?

me: <input type=hidden id='CredicardNumber' size='20' maxlength='16' name='CreditcardNumber' value=''

(4 minute pause)

Juan: sorry, send CredicardNumber

Of course the real WTF is that they return the values as hidden form tags in an HTML document. Not a real API interface ala URL encoded key value pairs or XML.

Sigh. Wish I could publicly call out the one I'm working on now. SOAP API, so everything's definitively named and typed. Documentation repeatedly refers to what experiment and WSDL inspection reveals to be the "reportName" parameter as "report id" or "Report id", and the "lineId" parameter as "line id", "Line Id", "LINE_ID".

And the guys here wonder why all my stuff is allways all lower case, no underscores or other special characters.

It'd be nice if people would embed testing procedures too; for instance, sending an all-zero credit card number would result in a null transaction but a typical return. That way you could try combinations and see if they work.

Shadow, in about 5 months, once I've implemented the web service client from hell, you'll have to get me drunk so I can ramble on about the contractual agreements about limits on testing hours, and minimum necessary time for all parties to implement changes to test protocols (I think it's 67 days, but I haven't religiously Gantt charted it all out), for a specific system.

A real API or XML transmission probably wouldn't make much difference, Meuon. In the past couple of years I have worked with two different data interfaces which had a host of minor problems like this. In each case it later turned out (usually revealed in chastened conversations after the fact with the API's author) that I was the first, or nearly the first, significant user - by significant I mean both "using the interface to a degree no one else had, not even the internal testers" and "more than willing to report bugs and push back on data issues."

The first was an XML DTD which had numerous little problems and no documentation. The guy was competent, and I like working with him, but initially I think I caught him off guard by accidentally torture-testing his receiving XML parser - "Oh, huh, I guess it doesn't like if that particular tag has no data; I didn't realize it would do that" or "Wow, I guess we need to CDATA that whole block." And, yes, a lot of case or keyword issues.

The other is a RESTful API for doing basic SQL-style operations over HTTP. I don't know that they ever really intended anyone not-internal to actually use it. They knew how to jump around its pitfalls and limitations, but had never documented those pitfalls for themselves or for anyone else. I'm pretty sure I have found all of them. My support emails to them now apparently automatically get forwarded to their lead developer. (In justice to him, I should note that he has always either provided an explanation of the pitfall or fixed the bug in a 24-48 hour turnaround! He's a good guy. I wish his bosses were as capable.)

#Comment Re: made: 2012-02-15 22:56:50.530809+00 by: meuon [edit history]

I'll sum it up by saying, our API's intended for outside use include actual working code as 'curl' commands. One .Net-ish developer cried with frustration when he saw it, and after playing with curl for Windows wondered how he did not know about it already and loved it.

1 line of a working curl command with data, beats 100 pages of documentation every time. How you code it, after you see it work is up to you. 20 working examples are even better. Makes a good "unit test" also.

Our API's allow you to pick the return format. All use basic authentication as a starting position. Most use a "get" style URL like: (all via https of course)

foo.com/vending.juice?mode=balance&account=1234&return=xml
foo.com/vending.juice?mode=balance&account=1234&return=json
foo.com/vending.juice?mode=balance&account=1234&return=keyval

All work the same, but return the data in different formats, with the right mime types. Pushing up data, instead of requesting, works the same.