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.
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.
Remember that the actual objects & signatures are pretty much an afterthought. Don't start with them. End with them.
You can follow @fchollet.
Tip: mention @threader_app on a Twitter thread with the keyword “compile” to get a link to it.
Enjoy Threader? Sign up.
Threader is an independent project created by only two developers. The site gets 500,000+ visits a month and our iOS Twitter client was featured as an App of the Day by Apple. Running this space is expensive and time consuming. If you find Threader useful, please consider supporting us to make it a sustainable project.