I was going to post the following reply to an issue on GitHub, but knowing the way things are going I'd probably get banneded for breathing an unkind word. And I need GitHub for my projects.
I know I'm replying to a 2-year-old post but it's a problem that persists.
There is no example showing explicitly how to insert something to any of your APIs, or at least it's not very visible. That's the biggest thing you could add to make this better. Just asking "how can I make it more clear?" when you made next to zero effort to make it so is asinine and condescending.
You might at LEAST throw a helpful exception. The default that gets passed along from the servers isn't at all helpful.
Most devs, when they see the words "request body", while they may understand what it means, they may even have intimate knowledge of the HTTP protocol, it doesn't necessarily click with them "this means the item I'm trying to insert". Their mind isn't necessarily working in the language of HTTP at that moment. They might not be part of a big organization where responsibilities for individuals are narrowly focused, meaning they have little time to think about this kind of thing this deeply. They may be unaffiliated hobbyists. They just want to make stuff happen.
It doesn't help that the Google APIs for NodeJS seem paper-thin. No promise support, hardly any abstraction at all. I don't see any reason you couldn't wrap up most of these calls in a thennable. But nope-- you'd rather spend the time writing new compilers for another custom language that only your people will use.
The point of an API is to abstract unnecessary details away.
This isn't a pointless exercise in UX for the benefit of developers who are going to be forced to work with Google's near-monopoly status anyway. This kind of thing fosters goodwill. It makes people love to work with your platform. It could mean the difference between a viable alternative popping up that starts eating your lunch when good devs jump ship or another decade of total dominance.
Go the extra mile. Damn.
This who situation shows a kind of casual pomposity. "Whaaat?! That wasn't good enough for you little children? How rude! You'll take what you get and you'll LIKE IT. Or at least not complain!"
Why does it seem like everything is calcifying? Not just in programmer culture or even Corporate America, but everywhere. There's no vitality in our culture anymore-- the biggest movies out now are rehashes of formulae the 20th century proved down to tedium. It's like people don't WANT to create beautiful things anymore. Nobody sees themselves in their output-- they live in a world of bland beige survival. Or they're narcissists whose only creative endeavor is in creating an identity for others' perception.
Jordan Peterson says that people are so afraid of being criticized that they squelch any creative impulse in themselves. They don't want to be told that they lack talent of have bad taste. It's easier to just daydream about what you'd do, and make excuses-- If only, if only.
It's why modern architecture is so ugly. You just do something "reasonable" that nobody can criticize because it's not supposed to look good. You use the most muted colors, the most nondescript forms, and maybe, just maybe nobody will notice it. And nobody will criticize it.
Honestly I didn't intend to make the connections I'm making. This is just stream-of-consciousness.
I think it speaks to a much deeper corruption in our society. Nobody takes risks anymore. Everyone is disconnected from their own destiny and from the world in general. We just all hold on, stay in the lines, until we get our little piece and then fuck the world. We are programmed drones, each restricted to their lane, told all our lives to stay in them and then through a sense of learned helplessness we stay there even when we should have grown up long ago. The adults who put us in this situation are are getting older and older, and when that generation of narcissists is gone we will be a civilization of children.