Ahhh, interfaces! Also known as APIs / protocols / behaviours / your-favorite-languages-jargon-term-here. The source of plenty of pain, much rejoicing, and far too much discussion. I plan on contributing, here and now, to that third category.

Continue reading

Definition

When I’m writing some function, there’s a general tradeoff between how abstract the function is, and how flexible it is. That's rather vague, so let's be a little more specific. It should be noted that for the entirety of the article, I'll be considering only pure functions with no side effects (e.g. no randomness, no IO, just pure data manipulation).

Continue reading

Look, I get it. Making a great API is hard. Nobody claimed it was easy! That being said, there are a phenominally lot of ways to do it wrong. The following is a list of problems that I have personally had in working with various third party APIs. Are these all super serious problems? No. Should I expect every API to not have any of these problems? Of course not; I myself am guilty of a number of these issues! However, the problems remain, and they are indeed problems, so without further ado:

• Your API doesn't use https. This is pretty basic stuff, c'mon now.
• Your API has a required nonce. Nonce's do basically nothing at all for security, and are really only good at making it a PITA for clients to consume your API in a distributed manner. At the very least, make it an optional parameter.
• Your API has rate limits that are ridiculously low, and prevent anyone from feasibly using it. I understand protecting yourself from overloading your systems, but if your systems are so weak I can't feasibly use it, maybe you're fixing the symptom and not the cause.
• Your API has reasonable rate limits, but doesn't convey back to the user what your remianing quota is, making it impossible to do any sort of intelligent resource management. If you don't let your users make intelligent choices, they never will.
• Your API rate limiting rules are so complex that they're not feasible to confidently calculate up front. This results in the same outcome as above; if you don't let your users make intelligent choices, they never will.
• Your API throttles me for a period of time but doesn't offer any indication of when the ban will be over. My only option is to poll your API to check if I'm still banned, which is obviously counter productive for both of us.
• Your API doesn't return unique identifiers for entities, making it difficult (and sometimes impossible) to de-duplicate entities.
• Your API returns multiple, different, unique identifiers for the same entity in different endpoints.
• Your API isn't self consistent, even accounting for eventual consistency.
• Your API is eventually consistent, but provides no mechanisms to know if the result of one endpoint is "before" or "after" in time from a previous operation.
• Your API isn't idempotent, or doesn't require an idempotency-like key for idempotency guarantees within a reasonable time window.
• Your API doesn't offer pagination or any other mechanism to properly traverse a large collection of items. This one is more of an annoyance than critical, but if you have a large collection of data on your API, people will want to iterate over the whole thing.
• Your API has various query parameters that have to be in a specific order or it won't work. This is entirely too brittle.
• Your API doesn't use HTTP status codes and instead uses an embeded "error" semantic to convey failure. Now my metrics tracking basic request failure rate have to live at the application layer, and not the http layer.
• Your API doesn't use error codes to differentiate between failure scenarios, and instead returns a string that is subject to, and does indeed frequently, change. Nothing I love more than discovering that I have a surging amount of "unrecognized" errors because you made a slight formatting tweak in your error messages.
• Your API returns error in a different place of the returned payload based on what error it was, forcing my error identifying logic to have to look basically everywhere instead of one spot. Actually, this can be generalized to:
• Your API payload has a different shape / data type based on context outside of what I asked for. I should be able to know the shape of what the result will be, before I actually receive it. Any sort of polymorphic deep nested fields type is confusing and puts application logic into the de-serializing layer. If your API endpoint can return different combinations of results based on context, then make your schema a flat product type over all fields.
• Your API doesn't have documentation, leaving me to deduce your functionality black-box style.
• Your API has undocumented behaviour. Inevitably this is only ever found out in production. Your consumers will not be happy.
• Your API documentation doesn't document all the possible error codes.
• Your API documentation doesn't properly describe what all the fields in the returned payload are. Am I dumb for not knowing what the (example) st field is supposed to contain? Or you should you just give it a human description in your documentation instead of only telling me that its a float??
• Your API uses POST for all requests, even read-only endpoints.
• Your API uses GET for all requests, even state-changing endpoints.
• Your API doens't provide websockets for updates that consumers would ostensibly want to know about, leaving them no option but to poll. This usually leads to all the rate limiting problems above.
• Your API isn't versioned, and so I can only assume that it is entirely subject to change with no notice, unless otherwise stated.
• Your API has different structures & semantics based on which resource I want, probably a result of different internal teams.
• Your API uses json web token in a way that json web tokens are not supposed to be used, which is too say, basically at all.
• Your API is only consumable through your custom "SDK" that comes with a bunch of bloat I don't want, and is only available in a language I don't use. If I can't use curl to inspect your API, that's bad.
• Your API uses numbers for precise decimal numbers. Financial APIs, I'm looking at you.
• Your API doesn't use ISO 8061 for dates. I'll also accept any form of unix timestamp, but only as a distant second best.
• Your API doesn't specify what timezone dates are in, and also uses different timezones based on context.
• Your API internal errors more than 5% of the time 😭
• Your API just straight up doesn't work properly 👿

Continue reading

Constants suck. These seemingly arbitrary limits are annoying and really kill the vibe of what’s possible. No FTL communication? Say goodbye to travelling the stars. Heisenberg principle? Fuuuuck that. Godel’s incompleteness theorem? RIP total understanding.

Never did I imagine that there are non physical limits though. Take meaning, true meaning. It requires time and attention, it’s impossible to find without either. In many ways meaning and effort are isomorphic, one and the same.

Continue reading

You know what I want? I want my own private server, to run my own private software, and I want everyone else to have one as well. Let me explain:

I’ll start with privacy; it’s at the forefront of a lot of people's minds these days. Down with centralization of power! Embrace web-style topology over the hub and spoke model!

Continue reading

People claim today that there’s more controversy than ever, and that might be true. If pressed to say why, maybe they’d point to all the protests going on around the world, twitter flame wars, and the general feeling that there’s just a lot of people online who seem like they want to be angry about something.

You could talk about the psychology of the issue, and you wouldn’t be off track, but if I had to put my finger on what really changed, I’d point to the abundance of information.

Continue reading

The paradox of the abstraction is that the more general the abstraction, the less it can tell you, and so the more useless it becomes. The essence of abstraction is to unify that which is common; the more that can be unified, the less you will find in common. When you’re limited to working only at the level of the abstraction, this can be extremely limiting.

In Seeing like a State, James C. Scott puts forward the idea that in their pursuit of control, States have negative effects on the quality of life of the inhabitants. The basic premise that the State can only make decisions on what it can see (understand), the state wants to see more, that there is a whole world of information that the State cannot see (Scott calls this metis), and that because the State cannot see the metis, the State inevitably ends up destroying said metis, at great cost to its inhabitants. I won’t dive into a full breakdown, for a fuller understanding I highly recommend this summary.

Continue reading

I get asked a lot about what I think about cryptocurrency. It’s a hard question to answer, nobody really knows what it is exactly. It’s different things to different people, and it’s not helping that it’s at least somewhat complicated to understand the underlying technology.

Part of why these discussions are hard to have is that there’s many ways of looking at cryptocurrency. You have financial analysts and governments looking at it as a regulatory nightmare with no oversight, and you have hardcore programmers looking at it philosophically as a tool against oversight.

Continue reading

I’m going to argue that declarative style programming is going to be the future.

When I say declarative programming, I’m specifically talking about a code style in which you specify what you want, as opposed to what you want to do. The most popular example of a declarative language today is SQL; you don’t tell the database how to filter and join and group and order and what-have-you-not, you just YELL at the database what you want.

Continue reading

The larger a corporation, the harder it is for me to believe their actions of selflessness are genuine.

It’s not hard to imagine a mom-and-pop shop helping out locals on prices, providing good customer support because they genuinely care, and sponsoring the local soccer team to support children. And yet, suddenly, when a huge corporation does anything public, it’s taken purely as profit-driven. They cut prices to increase sales, they give customer support in so far as they have to, and if they’re sponsoring anything, it’s only for cheap advertising.

Continue reading

I think that increasingly people are rejecting the reality that they are in, and that they’re choosing the reality that suits them the most.

Waaay back in the day we lived in caves, believed in Gods, and had very little information about just what the hell was going on. There wasn’t a whole lot to understand, mostly because there wasn’t a whole lot we could understand.

Continue reading

I’ve noticed that, for any given argument, there’s two core approaches: you can argue who is right, or you can argue what is right.

Arguing what is right is the rational act of finding out which base priors parties disagree on. This involves discussion of why each party believes what they believe, what support they have for said beliefs, and figuring out what information both parties are missing.

Continue reading