> Whenever you evaluate an API, or create a new one, you must always, always, ALWAYS start by writing some code as if you were a user trying to do the thing that the API is supposed to do. This is the only way to get a nice, clean perspective on how the API would work if it had no constraints on it whatsoever. If it was “magical”, as it were. And then, once you have that, you can move forward and start thinking about the practical problems, and what the best way is for you to get to something implementable.
Such good advice. It's so obvious but so easy to miss when you're excited to get things done. I think it's like writing a unit test before writing the code.
It changes your POV from an "API creator" to an "API consumer" - for whom this whole thing will be all about eventually.
Agree; it also helps to write documentation supporting the example. On several occasions I ended up reworking APIs I'd been working on after writing documentation for them, as some of the elements were too complex, looked inconsistent, or just didn't feel right.
I find TDD antethetical to this... you really need to actually understand the problem space - that requires large scale experimentation, not the micro-structuring TDD preaches.
> Maybe we should invent a paradigm and write a manifesto about it. We can call it... test-driven development.
Isn't test-driven development the opposite, though?
If the program is layered as layers A (main program), B (business logic), C (data objects) and D (persistent storage), TDD would have you first do the interface (and tests) for D before you do anything for C.
You only realise if D is missing something (or worse, has superfluous features) once you start doing C. Same when you get to B.
When going API first, you go top-down. You first figure out what the interface to the main program (A) should be, then you figure out what the interface to B should look like, etc.
I always have to program from both sides, and hopefully meet in the middle. You need your low level stuff before your high level stuff works. but you don't know what low level things you will need until you do the high level things.
My understanding is that TDD would start with the main program (A), testing functionality that is exposed to the final user. The later layers would only be written if and when they are required for the end-user functionality.
I think that User-Centered Design (UCD) would be a better term here for what this concept is trying to say. In modern design, we tell user stories that help guide development of interfaces, including APIs.
Too many developers put too much emphasis on the "A" (application) and too little on the "P" (programming, which should really be thought of as "programmer").
An API is a user interface in every sense of the term. Programmers, not abstract "applications," are your users, and so the same care taken for graphical UIs should be taken in designing APIs — e.g., account for your user's mental model, consider the outcomes your users want to achieve, consider the outcomes your business wants to achieve
Such good advice. It's so obvious but so easy to miss when you're excited to get things done. I think it's like writing a unit test before writing the code.
It changes your POV from an "API creator" to an "API consumer" - for whom this whole thing will be all about eventually.