previously, https://cohost.org/tef/post/219290-api-design-mistakes
with programming, there isn't so much a right way to do things, but there are an awful lot of bad ways, and the best you can do is try and fall into a new mistake than repeat the same ones, over and over.
then again, when you make the same mistake over and over, you call it a best practice, and sometimes doing the right thing ends up being the wrong choice, because no-one understands why you're doing it.
welcome to hell, no matter what you do, someone will tell you it's wrong.
this is yet another post where i present my opinions and tradeoffs in design as near absolutes, but hopefully i'll explain the reasoning behind them. i don't expect you to follow my dogma, but i do hope that you'll understand the consequences of your own api choices a little better.
honestly, most of this just comes down to taste