API Practices If You Hate Your Customers

> because parsing json is apparently icky and hard in brainfuck, their API language of choice I guess?

It's quite clear that what I'm talking about here has nothing to do with the ease of having a piece of software parse JSON, but with the difficulties introduced by thumbing your nose at helpful conventions in a context where "rough consensus and running code" has been brilliant at enabling a spectacular network of interconnected clients and servers.

It's less clear why you'd insist on returning to characterizing these points as "oh, you think JSON parsing is hard", but some of what it could indicate isn't flattering. Whether you're content with that or rueful about it at some point might also say something, though with any luck I will no longer be among those evaluating it.

> 11 5xx status codes. I'm glad to know these cover all possibilities for the software you write

Not my claim. My claim is that existing status codes cover some broad categories, and by recognizing what your status conditions have in common with existing HTTP codes, you can do early sorting across condition categories, and work in cooperation/re-use with other pieces of code and infrastructure.

> but you know what's even worse than anything we've discussed here? 15 different API's defining 512 to mean different things specific to their software.

Which of course applies equally to your individualized in-band error codes... that sword you were swinging cuts both ways, right? Except, of course, that they're not really exactly equal situations: if you 200-plus-response-body all the things, a client developer has to learn not only what your custom error codes mean without the benefit of working from HTTP-related conventions/groupings that you apparently won't engage, but they have to figure out which property/s they're passed back under when there's already a perfectly good standard for these things in the header information.

Contrast that with the situation of a developer who is working on a client that gets a status code header 512 back from an API written by someone who groks and tries to work with status code groupings. Even if the client dev has no idea what the server means by 512 specifically, they already know that it's not related to a user input or even a client request problem, and more importantly, code already written to deal with other 5xx errors either for this client or other clients knows at least that much too. If it turns out general 5xx handlers aren't adequate, they can turn to docs and/or response body info to learn more about 512 condition specifics and augment the general case with specific handlers (however rare the case may be in which a client might need to do anything other than relay API status messages).

> Yes, because you could never embed that sort of information into the JSON, that's not what it's for

You certainly could. You could also put all the other header information into the response body, too... Content-Type, Cookie info, Authorization headers, CORS, etc. For some reason people don't. Hell, I'll bet even you don't. Perhaps you'll ask yourself why. Perhaps not.

> It was me making fun of someone trying to argue that you would have to write code for the non-happy path in scheme A, but not B.

This isn't even an accurate summary of your comment, let alone an adequate characterization of or response to mine.

Good luck with your own happier paths. If you're as much more correct than I am about this topic as your rhetoric (if not your logic) seems to imply you believe you are, then I'm sure your decisions will be their own reward.

It's not cargo-cult: anyone who's worked on cross-browser front-end development probably encountered this at least once. I ran into this personally a few years back when I was trying to be too clever by half with base64-encoded queries. It's not just ancient IE that has limits - in my case it was a corporate proxy that was truncating the query (which is why only that customer was getting that bug). A year or 2 before that, I ran into the MSIE limit (must have been IE8 or 9: don't know if that counts as the Triassic period, because I don't know what we'd call the IE4-6 era)

The article doesn't mention POST. It says "the first time we call it the VM is created. The second time it is called the system detects that the VM already exists and simply returns without error". Makes more sense to assume it means PUT, defined as "The HTTP PUT request method creates a new resource or replaces a representation of the target resource with the request payload"