Comment by thanatos_dem | Hacker News Reader

Comment by thanatos_dem | Hacker News Reader

<rant>

I run a service that integrates with pager duty on behalf of our users, and man oh man did they make some poor design choices with their API.

The most glaring one is their integration keys, which is how you trigger an alert. They’re just v4 uuids with the hyphens removed, or in other words, completely random.

This is fine by itself, except they have two versions of their event API, and keys for the v1 API don’t work with v2 and vice versa. And there’s no way to distinguish what version a given key is for, since it’s just a jumble of bytes. We can’t even look up the service integration to find out what version it should be. We can using yet another different API, but even then it’s not clearly distinguished.

So now our users are confused about what version they should use. We only supported v1 for a while since there was no way to distinguish, but users kept using v2, which was failing cryptically.

So now we need to try v1, and if it fails try v2. But that means that our monitoring on errors are all fucky now since half the errors arent real errors.

In the grand scheme of things I guess it’s a relatively small design issue, but it sitting right in the middle of their one and only critical path, which makes it really painful.

I’ve alrwady contacted support about it and their response has been, more or less, “oh, uhhh... huh.”

</rant>

One of the nice little features that I appreciate about Twilio, and have adopted myself, is their API keys are always prefixed with a 2 character type.

e.g.

"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "phone_number_sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

Hard-won pro-tip: IDs should pretty much always have some sort of prefix when stored as strings, even if you swear you're never going to change them. You're not going to want to try to divine which id was which based on string length or what chars are where later.

I qualify "when stored as strings" because id numbers in database rows are in a sufficiently strong context on their own, for instance. But once they get serialized to strings, you really ought to stick a prefix on them. You may only change 10% of your ids, but the saving on that 10% will be well worth the cost of prefixing your ids.

But why this doesn't needed if you use numerical ids?

If you work on a sufficiently long lived system, you also discover that you usually want string ids instead of numerical ids.

Among other things, numerical ids are subject to enumeration attack (especially if exposed in a GET url parameters).

Yeah, we do this too in Arvados (https://arvados.org). All our uuids consist of three parts separated by a hyphen. The first part denotes the cluster, the middle part denotes the type of object, and the last part is a random string. E.g.

  qr1hi-j7d0g-a68mg4e5oh37oek

where 'qr1hi' is the cluster identifier, 'j7d0g' means 'project', and 'a68mg4e5oh37oek' is a unique identifier.

Do the same calls to the same APIs from the same customers ever change from v1 to v2 (or vice versa)? If not, can you record if it was v1/2 and then always make the same call after that? And then don't record errors for your initial probe request? Then your data will be clean and you'll make a lot less calls.

Yeah, we have some caching and retain metadata to avoid making more calls than we need to.

It’s just frustrating that we need to keep this information around on our side to mitigate issues with the API that is central to their entire business.

What's the big deal in checking if each version works?

Sounds like you just need to ignore the errors you get when testing the API version, e.g. wrap a try/catch block around the request.

If that's your big gripe with the API, you have it pretty good!

if you've ever logged into pager duty and tried to use it you'd know UX/ergonomics is not their strong suit.

You do realize the v1 API was deprecated last year?

That's only true of the REST API. The Events API has it's own v1/v2 split and I don't believe there has been any mention of the v1 Events API being deprecated.

that's it, this comment is a nail in the coffin of their future IPO.

Reply on news.ycombinator.com