Principles Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.

====== API Design ======

API design is the task of crafting [[glossary:interfaces]] to be used by an unknown amount of other developers. This is the case when designing [[glossary:APIs]], [[glossary:SPIs]], [[glossary:frameworks]], and [[glossary:libraries]] but also---although to a lesser extend---when designing [[glossary:packages]] and [[glossary:layers]].

The main difficulty of API design is, that any API needs to be stable. There is an unknown amount of other developers using the API so changing an interface results in a large amount of code to break. So while normally it is more or less easy to refactor an interface, this is not possible for APIs. Rather, obsolete interfaces typically have to be marked deprecated and maintained for years before they can be removed. Because of that, a different set of principles is needed here. [[principles:Keep It Simple Stupid|KISS]] (the simplicity of the implementation) is much less relevant. [[principles:Easy to Use and Hard to Misuse|EUHM]] (more or less the simplicity of the interface) on the other hand may be even more important.