Oh my god. It's full of code!

I Hate The Angel.com IVR API

This is a venting post. Very little useful information will be contained within. I guess perhaps it can act as a warning, but honestly, I’m just mad. It’s mostly meant to be cathartic, and perhaps a bit entertaining.

Here is the deal, Angel.com is an IVR provider. They let you make phone calls and set up call sites, etc. They offer an outbound API, which allows you of course, to make calls programmatically. Sounds good in theory. The problem is, I don’t think they really know how to build an API. Here is a quick outline of how I arrived at this conclusion.

1) Limited amount of interactions per API Token
For some reason Angel.com has decided it is wise to only allow a certain amount of API interactions per token. You use your credentials to get a token that is supposed to be valid for a given time period, however it is also only available for like 10 transactions before you need to get a new one. This adds completely unnecessary complexity to working with them. Pretty much every other vendor I have worked with gives you a token that is valid for a time period so you know when you need to get a new one. In this case I have to keep track of how many things I’ve done lest I end up over my limit and have my next call fail. This is lame.

2) Two types of call identifiers
This may be more personal preference than a legitimate gripe, but it does make things more sucky. Of course in a phone system calls can be inbound or outbound. Angel.com has two unique Id’s depending which kind of call it was. Of course this gets complicated because say you use the API to place a call, they give you back an outbound GUID (globally unique identifier), fine. Then someone answers that call and they enter your voice site, now it has an inbound GUID as well. Which one do you use for further transactions? Well apparently the outbound but that was just found out via trial and error as it isn’t documented anywhere.

3) Absolutely terrible getstatus call.
Once a call is placed I need to go back and figure out what happened with it, if it was answered, how long it took etc, so the call time can be billed back to the client. Of course I’ve had to build this complex logging system because Angel doesn’t really have any mechanisms to track which calls pertain to which client. So I have to use the getStatus API call and an outbound GUID (or a list of them), to get the data I need to build my log. This function, is completely, hands down, god awful, for a few reasons.

– Archaic return type: Instead of just having the useful information as text, it’s all returned in these crazy function wrappers. You have to spend half an hour inspecting the data that is returned and playing guess and check to see how to get the data you want. Why, why do I have to do this? What is wrong with returning simple text?

– Very fragile: If even one GUID in the list you send them is invalid for some reason, the whole list aborts. It’s completely all or nothing, meaning you have to get it perfect every time, which wouldn’t be so bad except….

– Random reporting of invalid GUID: For some reason, beyond any comprehension often times I get this error. Angel claims that one or more of the GUIDs I give them do not belong to me. Then where the fuck did I get them smart guy? You think I just conjured some fucking GUID’s out of thin air? Pulled them out of my ass and thought it would be funny for you to try and parse them? No you slack jawed backwards ass API, you GAVE THEM TO ME. I placed the call using the API, recorded the GUID in my database and now I’m trying to figure out what happened. Don’t you tell me it’s invalid, you gave it to me. Fine though, if you say it’s bad I’ll remove it from my list and pretend it doesn’t exist, well I’d love to except…

– Horrible error data reporting: If you get the above error, good luck trying to figure out what GUID is causing the problem. They give you the list of them, sure… but it’s just in a string.. after some error text, part of a stack trace and wrapped in some HTML formatting. That’s right… HTML formatting, in a web service call error message return. Not only do they not return an array with each GUID and it’s status, no, you get one text blob with the GUID’s that are presumable the problem just kind of… hanging out in there. Just chilling among the human readable error, the stack track and some mother fucking HTML.

annot perform web service invocation getStatus.The fault returned when invoking the web service operation is:<br> <pre>AxisFault faultCode: {http://schemas.xmlsoap.org/soap/envelope/}Server faultSubcode: faultString: Some of the CallGUIDs that you have submitted do not belong to you. SubscriberID: 40225 token: 0a14022d-0b-132634f962b-685b305c-ccb@40225@403e4852@1315926152748@1@1cef1c329a519114c4922915bbca946b GUID: [list of GUIDs here]

What the fuck is this shit?

GUID’s don’t want to be in that mosh pit, they belong as their own data structure that I can iterate over easily so I can mark that I shouldn’t try to get them again. Even after parse the text blob, cleaning the HTML, extracting the GUIDs and attempting to update my database so that I don’t attempt to get those statuses again, then I get this error…

– stackTrace:The email entered does not match our records. – WHAT. THE. FUCK. What the hell is this error? Email does not match your records? My credentials are hard coded in. These credentials just worked moments ago. Why now, all of a sudden as if being randomly smote by Thor does this error crop up? No real explanation, no reasoning, just error. Your credentials are bad, but yet good enough to get this far? My credentials half work? They exist in some kind of quantum super position of working and not working at the same time. Suck my ass.

So that’s about it. The main reasons I hate Angel. Apparently they have some new REST API which I’m sure they’ll tout as being better, but that doesn’t do me a ton of good seeing as I’ll have to rewrite my entire integration library to use it, and I have no guarantee it doesn’t suck just as hard.

Whew, I feel a little better now.

5 responses

  1. So why is it that APIs are so horribly designed? Why is it some developers, after having used well-thought-out APIs all around them, design such crappy ones of their own?

    It’s not just APIs. Java’s collection class is horribly designed–not just because it’s silly, but because it ignored (or was ignorant of) every shred of prior art they could have used as a model but instead to invent an inferior model of their own.

    Angel has lots of company.

    September 14, 2011 at 1:13 pm

    • Honestly I think the root of the problem is that most developers, including myself to some degree are egomaniacs. We always think we know the best way to do something and will “show” everyone else by doing our own awesome way instead of taking the tried and tested path. We all like to think we are smarter than the guy before us, and smarter than the guy who will come after us, smarter than our vendors, smarter than our partners generally just smarter. Of course this is not true, we are all different with different skills sets and I’d say like 75% of us are within a very tight bell curve of overall programming skill. It is this sameness that makes us strive to stand out by doing something different. After all, we are all just stuck behind keyboards. We aren’t rock stars or movie gods but yet we will want to be known and dammit the only way we can think to do that is by doing something really cool and new and original. Or so we think, but yet I can’t even name one famous programmer who engineered anything aside from the few ‘super greats’. Just the nature of the beast I guess.

      September 14, 2011 at 3:23 pm

  2. Daniel, this is Josh, the Head of Architecture at Angel. I’m sending you an email offline, but basically, I’m glad I came across this post and will be using it to help in an internal disagreement. You’ve got some valid points–these APIs have been around for a while and need refreshing. We’d love to work with you to make them as easy to use as possible. Get back to me here (or drop me a note back on my email). We’d love to involve your feedback as we improve our systems.

    November 16, 2011 at 5:20 am

    • Wow, this is surprising XD
      I responded to your email, and I would be happy to do what I can to help you improve your systems. I do apologize for the harsh tone of this post as well. I had been banging my head against the wall for hours trying to deal with the issues above and was pretty frustrated. I meant no disrespect to the people of Angel, just the product. I look forward to hearing from you.

      November 16, 2011 at 4:48 pm

  3. Anonymous


    December 16, 2011 at 9:03 am

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s