What makes a good API?
-
1. Enforces you to use it right
If you add some method or variable and “expect” people to use in a specific way just because you documented it, be sure it will not happen. API itself should enforce these things.
2. Easy to learn
Leave nothing ambiguous, put only 1 way to perform a specific action. If you can, make every item or method atomic. Make them perform a specific job without needing users to call some other method as a precondition.
Also sometimes it is hard for people to learn your API because the way you model a problem is very different than the way people model it. Be sure you collect your users basic needs and don’t put so much of your own mindset in it, the more you put your own mindset the less other people will relate.
3. Leads to readable and reusable code
This fails most probably when you have doubts to enforce users to code in a specific way and you make your API open for a free format usage. Maybe you think you have to cover all the needs in the version 1. When in doubt do not open a fire exit immediately, do not rush. Analyze the needs well, and just be flexible enough to add new features whenever a new need comes in the future. Do not try to address problems that are not clear yet. If the API does not enforce users to write readable and reusable code people will start to question its benefits and you should too.
4. Easy to extend
Be sure to separate functionality belongs to the API from those belongs to the module uses it. Ask yourself in what cases will i need to add new functions to API? Does that really need to be in the API? Be sure you provide ways to extend your API for those which belong to the user modules, otherwise API will need to grow in an undesired way by time.
5. Careful about naming
Choose same names for related things. You can also wrap some very important variables in meaningful classes or structs so people will understand more easily that they refer to the same thing. Also use self-explaining method signatures. Avoid abbreviations.
6. Minimalist
During development challenge yourself for questioning necessity of things in the API. If you can remove things without affecting the functionality just remove them. If you can give chance to users do same thing it in less steps just do it.
7. Unit Tested & Complete
This one i am not even gonna explain ;) Beside the known benefits of unit testing it will also be a good documentation of what your API does.
