how to tell if an API works well before you write the integration

I connect with APIs for a living, or at least for part of a living. I do it all the time.
Often the ops team will ask me - how long to do an integration with ESP X, or Analytics firm Y? short of actually doing the integration, it used to be hard to give a good answer to this question. Now, tho, I have the perfect heuristic - it's never failed me.

Just take a look at the API docs. doesn't really matter what they say; if they're well formatted, easy to navigate, and well thought through, API integration will be a breeze. That simple.

Something like this makes an easy heuristic:

• no API docs - refuse to do the job
• API docs not available online but emailed to you in pdf form (or shared as gdoc): 40-50 hours
• API docs in one monolithic html page: 30-40 hours (obviously all of this depends on depth of integration too)
• docs have a formatted nav bar at left and some readable styling: 20-30 hours
• docs have the above in addition to "web 3.0" style formatting, and maybe some helpful examples: 10-20 hours
• docs have the above plus toggleable examples in different programming languages, maybe a link to wrapper libraries, are well written, and code blocks are formatted with special code block formatting: 1-10 hours.

you can use this, free of charge :)

best part of it is that I taught the ops team how to do this, and now they know exactly what estimate I'll give before they even ask me. Pretty soon they won't even need me at all, what with services like zapier.

more python SUDS advice

Everybody knows the a SOAP API is a horrid thing to work with, even a well designed one. But everybody also knows that SOAP is going to be around for a while.
Recently, while working with the ExactTarget SOAP API in Python, I figured out another helpful trick with SUDS, which is the main python SOAP wrapper.

Let me preface this by saying that suds is not a great library; particularly, it was written by and for people from another era of web development and does not stand up to today's needs. Why doesn't somebody write a better one? because everyone who does modern web dev hates SOAP in the first place.

But anyway, one annoying feature of suds is that when you create an object from its object factory, it always fills in all properties with an empty string, even those that are optional and have sane defaults. So essentially, it breaks all objects right out of the gate, forcing you to go through one by one and choose those sane defaults explicitly.

However, there's another way - for any properties that are giving you trouble in this fashion, just delete them after creating the object:
del object.AnnoyingProperty

Suds will then not send the property, allowing the API server to choose the sane default.

facepalms: 6

magento and the dreaded WebFault: Product not exists

Sometimes using SOAP with the Magento V2 API you may search for a product's image (by calling catalog_product_attribute_media.list with the sku as only argument) and receive this hilarious message:

"Product not exists." <-- you can't make this stuff up!

Hilarious but sad, because there's the image right there, laughing at you from the website, and yet your API doesn't have access.

luckily there's an easy fix. in short: append a space to the end of the sku. done. psha. magento, we love to hate you.

facepalms: 5

suds empty tag issue

I just posted a really nice Stack Overflow solution about this:
http://stackoverflow.com/questions/9388180/suds-generates-empty-elements-how-to-remove-them
The general point is that although Suds is an awesome python library that lets you connect to SOAP clients (I mean, really? welcome to the 21st century, people) with relative ease, it has the bad habit of adding empty tags for optional properties of objects. This tends to confuse (poorly written) API endpoints.

facepalms: 6