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.