3SidesToEveryAPI
From APIDesign
Not many things we know have just a single meaning. Often, depending on the point of view, there can be multiple truthful ways of describing properties of the same object. Throughout the Practical API Design book I claimed beauty is not important, however after reading Petr Hejl's recent blog post Beauty Matters, I can't do anything else then nod in agreement. Did I change my mind? Do I see why beauty matters in API design now? Well, maybe. But more importantly Petr made me realize that term API is not a single indivisible entity, it can probably have at least three different meanings.
TBD: Geometrical point is indivisible, always the same. Line, divisible, but always same. API, is interface, a line, between at least two things, as such it should be as clear line!?
Contents |
Yours
The most common point of view to an API is the point of view of its users. Usually, there is much more of API users, than its writers, especially in case of successful and widely used technology. As such the amount of eyes looking from this point of view massively out-weights any other observer.
It seems to me that Petr's Beauty Matters is mostly talking about APIs from this angle. People who are using an API of some technology have the right to be able to create beautiful code. Indeed, beauty in this case is again highly subjective, what is beautiful code for someone, can be one of the most horrible mess when inherited by other developer. But this is completely different story. All that is necessary from the API is to allow its users to write code that they like themselves. Because if their code is beautiful for them, they are more happy, do less mistakes, etc. Beauty is important here, as it increases acceptance, and happiness, simplifies maintenance. Here I fully agree that beauty matters.
Mine
The other way to look at an API is from the point of maintainer. For us, those who maintain some API, this is the view with our own eyes. This is how we see our APIs daily - the way we design them, document them, maintain them, the way we modify all the internals hidden behind the API facade.
Indeed, as regular human beings, we'd like to see beauty, we are more happy when what we do is also nice, however keep in mind there is one maintainer of an API and many users. As such when you need to decide whether make life simpler for us, or for our users, sacrifice yourself. This is actually the point of view presented in TheAPIBook and this is the reason why I often suggest that beauty does not matter - it does, but not the situation where an API maintainer refuses to simplify life of its API users because it would make his own code ugly.
Good API is a facade over the internals of the API implementation. A nice facade can completely hide all the mess and ugliness visible to the maintainer. It is just necessary to have maintainers that is willing to sacrifice, give up on own desire to have beautiful code and still write code that is reliable and correct. Because, beware, abstractions leak over facade. And as soon as unmaintainability leaks, even your users will not be able to write beautiful code. Which, obviously, make them quite upset and angry against your API.
The Truth
TBD: The role of the API of its own, without an observer. Can it make its every observer satisfied? It is "interface" - can it really separate its observers? Can it separate the client from the maintainer? Or client from the provider? A lot about freedom to change (each observer, without interfering with others) evolution aspects.
The Role of Beauty
Important on the "Yours"/Clients (Petr's point). Sacrify yourself if you are producers of an API (TheAPIBook's point).
TBD: Mention tribute to wikipedia::III_Sides_to_Every_Story. TBD: Category:APITypes
Follow
