How not to maintain an API

We license a vendor’s services for corporate information, like annual revenue and office locations. Their name shall be kept confidential in this story.

We access their API via http calls. They call it a REST API. But like 95% of the “REST” APIs in the world, it’s not REST at all, and in fact nowhere near REST. The term “REST” has been corrupted to be become synonymous with, “web API”.

But whatever. It’s an API accessed with http calls.

One of service calls has a parameter called, “countryCode”, which was documented as an ISO 3166 country code.

I coded up new features that used this API. And I wrote unit tests, and debugged the code on my dev box up to a reasonable point. (It was a “reasonable point” for typical vendors, but not this one, as it turns out.) I then propagated it to the trunk, and uploaded it to our QA system.

As soon as we started system testing, we noticed they didn’t recognize some valid codes. Like the one for United Kingdom (GB).

After thoroughly checking our code for bugs, I submitted a ticket asking them to investigate. Two weeks go by with no response. Then the answer comes back: “Oh, oops. For some countries, we don’t use ISO 3166. Instead, we use our own internal codes. <I won’t bore you with their reasoning, which was nonsensical.> So you need to replace ‘GB’ with ‘UK’.”

I pointed out that this was odd, fraught with peril, and undocumented. What happens when ISO 3166 adds codes that collide with their codes? I received no response.

I sucked it up, coded a dict replacement table, and updated our servers. (I should have manually tested this. But I was pressed for time and hadn’t yet woken up to their level of intellectual rigor.)

Now the calls with “UK” were bombing!

I submitted another ticket. A week later the response comes back: “Oh, ooops. UK won’t work either. You must submit the country in which the company is located. We accept the special strings ‘england’, ‘scotland’, ‘northern ireland’, and ‘wales’; we don’t recognize any symbol for the United Kingdom.”

WTF. WTF to the max. This was absurd in an indeterminate number of ways.

I realized I’d have to create a UK gazetteer to do this. This is the subject of another blog post, but suffice to say I built a city:country UK gazetteer, hacked our code to use it, and uploaded to our servers.

Yeah, I know, I should have manually tested what they told me. I’ve since learned my lesson.

As soon as the new code was on our QA system, I saw that these service calls still didn’t work. So I contacted them again.

A couple of days later the answer comes back: “Oh, ooops. You should use ‘GB’ for the country code after all. We don’t recognize the country names you submitted.”

WHAT. THE. ACTUAL. FUCK.

I counted to 100 and very tartly replied that we started down this path by using the ISO 3166 “GB” code in the first place, and they hadn’t recognized it. Why should it now work? Are you changing your API without any versioning, notice, warning, or documentation changes?

They didn’t reply to this.

I stomped around the office for a few minutes. Then I ripped out the hack code and gazetteer table, so the ISO 3166 “GB” code would be used in our service calls. And again updated our servers.

Presto, the calls now worked as advertised.

And that’s how not to maintain an API.