There’s plenty of API horror stories out there, I figured I’d share mine. This is a story of a certain API of a certain piece of software and the trials and tribulations I went through to avoid making users upload a CSV file.
Background: There’s not a lot of software in the space of the company I was working for at the time. The quality ranges from poor to less poor and my company opted for one of the less flexible more stable bad options–I will call it Athletic. This was customer facing software that had a very decent user experience if you were a customer and a very bad experience if you were actually paying for it.
So I’m building a web app to be used internally at my company which needs data from the software in Athletic. The options are: 1. Download an excel spreadsheet that you can export from Athletic, convert it into a CSV, and upload it. This works, but is a painful process for users and this will need to be repeated weekly, sometimes more often. Option 2 is to use Athletic’s API. I opt for option two. So the odyssey begins.
The first part of the process is to obtain an API key. There is no automated means of getting one, and I as a sub-user of Athletic can’t apply for one–it had to be done through my boss. So he reaches out and gets me a token. I don’t need it at that very moment so I don’t test it. Little do I know the pain this will cause me.
A week goes by and now I need to integrate with Athletic to populate data into my software. I search for an API documentation–there are three for three different APIs they support. None of them are for the sub-software my company is using. I contact Athletic and get sent an enormous PDF with a massive amount of documentation on API versions 1-3, though 1 and 2 were deprecated already. The documentation is not very good however, and getting my first query is a challenge.
I send the query through Postman and get this mysterious error: 500: TOKEN EXPIRED. “Oh no!” I thought, “I waited too long and my API key must have expired!” With my tail tucked between my legs I tell my boss I need another key and he gets me another one. I execute the same query, and, lo and behold, I get the same error. My boss contacts Athletic’s support and tells them about the error, I get CC’d and the support adventure began. I tell them my issue and receive silence. I figure I’m probably on my own here.
Maybe I’m not authenticating correctly. I see in the documentation that there are a few ways to do it, so I try the others. One of them is to use your username and password from the site–remember this detail. None of the other authentication options work.
Doing a deep dive into their website I see that there is an interactive API tutorial. I attempt to use it, but it crashes my browser.
Next I encounter their forums, and hey! There’s a section about their API! I open it and don’t know whether to laugh or cry. The first page of the sub-forum is all spam, things like FREE PASSPORT BUY NOW CHEAP and CAST VOODOO CURSE GET LOVE. As I am not looking for bootleg passports or shamans, I continue to the next page. More voodoo spells, more scams, and spam. Around five pages in I encounter the first real post: “Does this API work at all anymore?”
You can guess how the post read. “Hi guys, I’ve been getting a weird error and Athletic support hasn’t gotten back to me. I keep getting 500: TOKEN EXPIRED but I got my key a few days ago. Does anyone know how to fix this?” No responses. This was posted years ago.
Days go by and I finally get an exciting message in my inbox! It’s Athletic support! They want to help! I’m saved!
It is of course T1 support, reassuring me that I’m doing something wrong and that API keys don’t expire. I send them my error they ask me to send them my API query. I send it and receive an email from a different member of their support team. They tell me that I’m doing something wrong and that API keys don’t expire.
I tell them that I am already talking with a different member of their support team but they seem to ignore this. We’ll call my first support friend Alex and my second friend Sadie. A tree diagram would be the best way to represent how this process continues but I’ll do my best with bullets.
- Alex sends me a query to test. It is almost exactly the same as the query I wrote. I test it, it does not work. I tell her it did not work.
- Sadie is a step behind and asks me to send her the query I’m trying to execute.
- Alex tells me she is escalating my ticket. The excitement is building.
- Sadie tells me the query is working for her, I tell her it is still not working for me. She sends me a query to test. It is almost exactly the same as the query I wrote. I test it, it does not work. I tell her it did not work.
- Sadie says she is going to talk to their developers–she doesn’t escalate my ticket though.
- A developer from their team who we’ll call Jim contacts me and tells me that I’m doing something wrong and that their API works fine. This is where things get bananas.
Jim sends me a different company’s API credentials and a query to test. It is an undocumented feature that anyone’s API key can be used to view any organizations information. It’s a really good thing their API doesn’t work I think to myself–however… I execute the same query using the other organizations API key, and it works like magic. I’m flabbergasted. Is it my key? Is it my credentials? I tell him the query works and he closes my ticket without fixing my own token. So I start integrating my software with a Athletic’s API using some other company’s credentials. I realize this is horrible practice, but I an now extremely close to the deadline and need a quick and dirty way to move data. Then my next issue.
Executing a query to get the information from one user works fine. Two is a little slow. More than two sometimes times out, more than five always times out. I attempt to do some hacky daisy chaining of queries but this results in my own server timing out. There is no way to use the API the way I needed it. The only way forwards is to use the spreadsheet. Fine. I write the integration. It’s not pretty or reliable but it works for now. I end up mostly doing the imports myself anyway.
Remember our friend Sadie? She finally gets back to me. “Could you please send me your username and password?” This is where I get off the ride.
Shortly before my tenure at that company ended we switched to a different piece of not-great software, but a not great piece of software that had a functional API. It was beautiful. No support gang needed, just functionality out of the box.
That was my worst API experience, but not my worst bug. Stay tuned.
As always this post is brought to you by SummerTech Computer Camps, my current (wonderful) employer and the camp I went to as a kid! If you are a or know any youths between 7 and 17 who are interested in CS, check out https://summertech.net! We have locations in NY and MA.