This is a great document. Lots of detail, good recommendations. I recently gave
a short lecture on API design and came up with the following "touchpoints" of
API design. These are sort of general guidelines and a lot less specific than
the article was.
orthologonal - Properties and methods should not overlap in functionality.
If two methods do sort of the same thing but differently that
is a design issue. They should either do entirely different
things or there should only be one method. Providing two is
confusing and can potentially lead to bugs.
consistent - Naming of methods, properties and other entities should be
consistent. Example if you have a method "getColor" you should
not have a method "get_width" or "width" or any other variation.
You should stick with one format. In the same way argument orders
should be consistent. For example, if you have a method
"translateCoords(x, y)" you should not have a method
"setTopRight(y, x)". This principle is extensible into other
domains as well (such as exceptions).
composable - Methods and functions should be reasonably composable. Instead of
creating giant methods which do many things create small methods
which do one thing really well. Then provide a clear way to
compose methods together in order to accomplish a task. In this
way methods do not have to be written which explicitly perform
complex tasks.
learnable - All design is for naught if the API is not well documented. Much
has been written on the importance of this step but it should be
stressed again. Good documentation can make up for any number of
short comings in the design. So document your api, provide
examples of how to accomplish tasks.
discoverable - Hand in hand with documentation comes the ability to be able to
naturally discover other parts of an API. This can be provided
in a number of ways based on language and platform. In Python
providing great dynamic help via the "help()" command and
docstrings is a good start. For web APIs consider providing an
"explain" API which returns documentation.
A valuable advice. I'd add purposefulness, for the lack of better word. API is usually intended for some specific use cases, and it's important to communicate what these are—in documentation and in API design itself. (Although this point could be seen as an extension to your “provide examples of how to accomplish tasks” suggestion, it probably deserves its own mention.)
I'd also say that discoverability does not matter as much as documentation, IMO only very extensive APIs with lots of endpoints would actually benefit from it. I.e., in the case of web service APIs, don't waste resources on implementing complex nested endpoints with discoverability and HATEOAS when just a bit of clear documentation would do.
I believe that the word orthologonal should read orthogonal.
I don't mean to downplay your points; I agree wholeheartedly with your post, but I actually did a double take and thought I might have been spelling the word incorrectly for some time.
orthologonal - Properties and methods should not overlap in functionality. If two methods do sort of the same thing but differently that is a design issue. They should either do entirely different things or there should only be one method. Providing two is confusing and can potentially lead to bugs.
consistent - Naming of methods, properties and other entities should be consistent. Example if you have a method "getColor" you should not have a method "get_width" or "width" or any other variation. You should stick with one format. In the same way argument orders should be consistent. For example, if you have a method "translateCoords(x, y)" you should not have a method "setTopRight(y, x)". This principle is extensible into other domains as well (such as exceptions).
composable - Methods and functions should be reasonably composable. Instead of creating giant methods which do many things create small methods which do one thing really well. Then provide a clear way to compose methods together in order to accomplish a task. In this way methods do not have to be written which explicitly perform complex tasks.
learnable - All design is for naught if the API is not well documented. Much has been written on the importance of this step but it should be stressed again. Good documentation can make up for any number of short comings in the design. So document your api, provide examples of how to accomplish tasks.
discoverable - Hand in hand with documentation comes the ability to be able to naturally discover other parts of an API. This can be provided in a number of ways based on language and platform. In Python providing great dynamic help via the "help()" command and docstrings is a good start. For web APIs consider providing an "explain" API which returns documentation.