To Boldly GET: I Built a Starship Out of Status Codes

A week and a half before I started at SerpApi, I was watching Star Trek and it hit me that I could easily remember HTTP status codes using Star Trek puns. Maybe it’s my British sense of humour, or maybe I’m just a big nerd, but it seemed like a fun idea. And before starting any serious work, I wanted something to build that was quick to change and didn’t need to be right about anything, because I’d spent weeks on API libraries where every decision has an RFC behind it, and this was going to be a few days of the exact opposite.

Oddly, I didn’t start with the starship. On the fifth of November I opened the Museum of HTTP. It was a lobby and three exhibits, each one a status code with something to press, and each exhibit linking to its page on apiguide.dev, which has a page for 63 of them. That number turned out to matter, because it gave the museum a collection to fill and a point where it would be finished.

An hour and a half after that first commit, it wasn’t a museum any more. It was the USS Keepalive, a starship where every compartment is a status code, and all 63 of them were open.

The teapot did it

The museum lasted about twenty minutes. I redesigned it around huge numerals and flat colour, opened rooms in batches of five, and it was a perfectly reasonable little site.

Then I got to 418, I’m a teapot. Every time I’ve ever heard that one, I could imagine “Tea, Earl Grey, hot”, and a teapot that refuses to make coffee is already halfway to a replicator that refuses to make coffee. So I tried a starship theme on that one room, just to see. You order a coffee and the replicator answers 418. Ask for tea, Earl Grey, hot, and it’s a 200 with “There, was that so hard?”, and if you ask for it lukewarm you get a 406 and the captain coming down personally.

This is that room, cut down to three orders, so you can try it here:

It was obviously better than everything else on the site. So the next commit turned the whole museum into a ship. Exhibits became compartments, the lobby got a deck plan, and the rooms that were already open got rewritten in the voice of a crew that’s mildly exasperated with you.

I’ve borrowed from Star Trek before, when I named the parts of Relay after it “because why not?”, but this was the first time I let it take over a whole project.

Why it works for HTTP

The thing I didn’t expect is how well the two fit together, and I think it’s because a status code is already a little character. It has a name and a mood, it only ever turns up for a reason, and Star Trek happens to have a character, a species or a running joke for nearly every one of them.

410 Gone is the crew lockers, where Ensign Dave’s locker still has his name on it, because Dave went on the away team in a red shirt. 426 Upgrade Required is a Borg cube, which is the most honest description of a forced upgrade I’ve ever seen, and the response comes back with Upgrade: collective/1.0. 402 Payment Required is a Ferengi trading post that only takes gold-pressed latinum, and it quotes the Rules of Acquisition at you while it refuses everything else. 451 Unavailable For Legal Reasons is a records office belonging to Section 31, which doesn’t exist and would prefer you didn’t read this. And 508 Loop Detected is a temporal causality loop, where everybody has deja vu and nobody can say why.

The rule I ended up following for every room was that the joke had to be true about the status code. If a joke only worked as a Star Trek reference, it was a worse room, because the whole point is that you come away actually knowing what a 426 is. The Borg room works because a 426 really does mean the server won’t talk to you until you switch protocols, and resistance really is futile.

Checking the canon

Later that afternoon I went back through every line I’d presented as real Star Trek and found that a lot of them were paraphrased from memory. That bothered me more than it probably should have, so I replaced them with the real wording, and checked each one against a source.

That turned up a few surprises. The Prime Directive, which runs Room 405, Method Not Allowed, was only shown in full in 2021, in the Prodigy episode “First Con-Tact”, even though the original series had used most of it in “Bread and Circuses” decades earlier. Memory Alpha, the obvious place to check, blocks scripted reads, so the checking happened against Wikiquote and episode transcripts instead.

I think being a fan and being an API person are the same habit, really. In both cases somebody is going to read what you wrote very carefully, and they’re going to notice if you got it wrong.

Making it feel like a ship

On its own the theme was only ever going to be a coat of paint, so most of the work after that first day went into making the site actually behave like a ship.

There’s a stardate in the header, and it’s live. There’s no official formula for stardates, so I used the rule of thumb the writers used, a thousand units a year, with 41000 at the start of 2364, and treated 2026 as 2364:

export function stardate(at: Date): string {
  const year = at.getUTCFullYear();
  const start = Date.UTC(year, 0, 1);
  const end = Date.UTC(year + 1, 0, 1);
  const units = 41000 + (year - 2026) * 1000 + ((at.getTime() - start) / (end - start)) * 1000;

  // Truncated, so it never rounds up into a stardate that hasn't happened yet.
  return (Math.floor(units * 10) / 10).toFixed(1);
}

The truncation is the only line in there I had to think about. Rounding would occasionally show you tomorrow’s stardate for a few minutes before midnight, and that felt like exactly the kind of thing someone would email me about. Here it is running, and you can look up any date you like:

If you try the 28th of September 1987, the night The Next Generation first aired, you get stardate 2741.0, which is a very long way short of the 41153.7 that the first episode opens on. That’s what you get for using a rule of thumb from a writers’ guide as an actual formula, and I’ve decided I’m fine with it.

Every room has a console. It shows the request and the response, and the ship’s computer reads the answer out first. A success is “Acknowledged.”, anything that was your fault is “Unable to comply.”, and a 5xx is “Warning. Unable to comply.”, because those are things the computer actually says. Any 5xx also sounds red alert across the whole ship for a few seconds, with the edges of the screen glowing red and the words flashing at the top. There’s no sound. A website that starts making klaxon noises gets closed. You can set one off here, in a cut-down Warp Core, by asking for warp 9 twice:

And moving between rooms goes to warp, with the stars stretching into streaks and settling again as the next room arrives.

The ship itself is my own design. That’s on purpose: it’s a long wedge hull with slung engine pods and no saucer anywhere, there are no official logos, and none of the screens copy anything from the shows. The footer says what it is: an unofficial fan project, not affiliated with or endorsed by Paramount or CBS Studios, who own Star Trek.

What it gave back

I built this for fun, before the serious work started, and it’s ended up changing some of that serious work anyway.

I’ve been building a talk called Evolving an API Without Breaking Everyone, and it now borrows a lot from the ship. The status codes the talk turns on are rooms, a breaking change sounds red alert, and the whole talk is set up as a mission to change an API without sounding it once. It’s a better talk for it, because “and then their integration broke” is easy to nod along to, and a slide that suddenly goes red is much harder to forget.

Come aboard

The USS Keepalive is at keepalive.juststeveking.com. Every compartment has something to press and every one of them answers back, and the deck directory in the lobby lists all 63 if you want to go looking for a particular code. If you only try one thing, go to the Warp Core and keep asking for warp 9 until the chief engineer stops being polite about it.