"ALWAYS start by writing some code as if you were a user trying to do the thing that the API is supposed to do."
It still amazes me how many times junior devs ignore this. They will spend a lot of time walking through the UX scenarios, mocking it up, etc. But when designing the API layer, they just start creating end points instead of focusing on the "DX" scenarios (developer experience, not theirs, but devs using the API).
I remember reading Cwalina's "Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries" and really learning what that means. It is a book focused on .NET but I wish many of my colleagues in the open source world would get over that and just read it. It would change their view on API design. And that is just the first chapter.
I do a modified version of this, mostly because I find if I start by writing code calling a "magical" API I sacrifice too much in the implementation to make the API exactly match my design.
I do start by writing code to solve my problem without an API, then work from there to derive a sane API. Usually something reasonable falls out from that, without forcing the machine to bend over backwards to support what I'm doing.
I don't think this is a bad principle—APIs ought to make common needs trivial to meet. I do think it's an over-simplification that's worth refining.
(As an aside, I'm becoming more and more convinced that libraries implementing network protocols should pass network transport duties to the caller, at least in C-family languages. It seems worse for the caller, but trying to work e.g. a WebSockets library into a project with its own I/O event loop is its own exercise in pointless frustration.)
Hmm, my experience was the other way around; the junior devs who'd read their Agile books always did this, it was the senior devs (or architects) who would produce baroque APIs that exposed all the possible options but didn't help you with any use cases.
The second edition of the Framework Design Guidelines book was written in 2008 and seems (from a 10 minute browse of the first chapter) to be pretty up to date still.
It's ISBN 9780321545671 if anyone's looking for it (it's on Safari Books Online, too)
Yea unfortunately, this is one of those things one really end up learning by experience. Once you've been writing code for long enough (and especially in a codebase that's been highly) is when the developer experience starts to be a thing that really occupies your mind when building.
Yeah, when I make API's or configs(or whatever) I usually start with the message(or config) format that I would want to use myself, then go from there. I should think for people wanting to use their own API's that would be pretty natural though.
It still amazes me how many times junior devs ignore this. They will spend a lot of time walking through the UX scenarios, mocking it up, etc. But when designing the API layer, they just start creating end points instead of focusing on the "DX" scenarios (developer experience, not theirs, but devs using the API).
I remember reading Cwalina's "Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries" and really learning what that means. It is a book focused on .NET but I wish many of my colleagues in the open source world would get over that and just read it. It would change their view on API design. And that is just the first chapter.