Taking this a bit further, it's surprising how many companies sell API as a service but provide minimal support for that API, publishing like 1 client/sdk (and often not in the language you need, lol).

Just mindblowing that companies don't adopt a schema-first approach to appeal to a broader customer base. I've lost count of the number of hnd rolled clients I've had to write over the years.

It gets even better if the API itself is backed by some RPC framework. With that, users can simply generate a client and get going.

It feels like we can do better as an industry, this cracked me up because it's so true.

"a single JSON example as the only documentation is... unfortunate"

Funny you should mention nullability. That was a big debate in proto2 vs proto3.