An API has two sides: first, the mental models underlying it, which should straightforwardly map to the mental models of domain experts. Then, the actual objects/signatures of the API.
API design is mostly about designing the 1st. The 2nd is just a mechanical consequence of it.
API design is mostly about designing the 1st. The 2nd is just a mechanical consequence of it.
So to design a new API, start from expert mental models and end-to-end workflows.
The worst APIs I've seen originated from confused mental models. You can't create a simple language to specify how to do XYZ if you don't have a crystal clear understanding of XYZ.
The worst APIs I've seen originated from confused mental models. You can't create a simple language to specify how to do XYZ if you don't have a crystal clear understanding of XYZ.
Remember that the actual objects & signatures are pretty much an afterthought. Don't start with them. End with them.
