Let's start with the takeaway --

Spread your diversity of client workflows across a minimum of a diversity of API workflows.

What's that mean?

Let's use a relatively benign example involving MySQL. It has an incredibly flexible API. For any particular goal, there are several ways to accomplish it. What if you want to store a timestamp?

• You could use the datetime type.
• You could use the timestamp type.
• You could use an int, representing it using seconds since epoch.

So you let's say from these, you choose to store it as a datetime. Not because it offers a specific needed feature, but because it seems convenient. The following week, you're in a mysql shell, wondering how to write what should be a simple query

SELECT * FROM users where datetime_created < ...

How do you compare a datetime in a WHERE clause?

For instance, Mon Apr 6 22:50:09 UTC 2020, which is 1586213409 as seconds since epoch.

• Do you just write 2020-04-06 22:50:09?
• Or turn it into a string, like '2020-04-06 22:50:09'?
• Or perhaps DATETIME(2020-04-06 22:50:09).

The answer here isn't relevant to the essay. The point to highlight is that this spent time to find a workaround did not need to exist in the first place!

If you used a integer, then your expectations of MySQL would be the same as the rest of the integer types that you have. You would have reduced the burden of learning necessary for developing in this system, which in turn improves your development velocity and reduces your bug risk.

This example was relatively benign -- the main problem being extra development complexity. The core of the issue though is that more diverse API workflows yields a higher chance of gaps in expectation. With more gaps in expectation, you get an increased chance of bugs and outages. Consequently, you can reduce this by spreading your diversity of client workflows across a minimum of a diversity of API workflows.