3SidesToEveryAPI

From APIDesign

Current revision

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.

Yours

The most common way to look at an API is to use the view point 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 still highly subjective, what is beautiful code for someone, can become one horrible unmaintainable 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 own code is beautiful in their own eyes, they are more happy, do less mistakes, are more productive, 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 its maintainer. For us, those who maintain some API, this is the view through our own eyes. This is view is our daily bread. This is the view we get when we design our APIs, document them, maintain them. As this is what we do day be day, we may start to believe that this is the most common view, that this is the most important one.

Indeed, as regular human beings, we'd like to see beauty around us. We want to feel more happy by writing nicer code. However keep in mind there is just 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, it should be a simple choice. 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 in 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 cluelessly hide all the mess and ugliness visible to the maintainer. It is just necessary to have maintainers willing to sacrifice, giving up on own desire to have beautiful code and not giving up on writing correct and reliable code. 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, can make them feel unhappy when struggling with the API.

The Truth

Since the Greek days the truth is supposed to be objective, ever-lasting and as such it cannot be associated with any viewpoint. Or, in other words, it cannot prefer an individual point of view, either it needs to balance between all of them, or it needs to stand out of the system. Truth should be truthful on its own.

If we take this look, then the important part of API is the interface. An interface is a thing between you and me, or among various actors, having their views. The interface is good if it serves its role well. Which means, if it really separates the involved parties, yet it allows them to talk to each other. Can an API separate its user from the maintainer? Does it help the user to approach the application in the intended way? Does the API isolates actions taken by client calling into it from the life lived by provider of the services?

Many of these questions are objective, and can be evaluated without the need to usurp a single point of view. As has been argued in Chapter 3, all the properties of Good Technology may be present in an API, without the necessity to make the API really beautiful. Definitely not from the maintainer's (e.g. mine) point of view.

Notes

Beauty matters from Yours perspective. Clients of an API need to be pleased, need to feel the beauty while using it. Only then they feel they are using Good Technology.

Beauty of Mine is unimportant to them. This is a sad truth for the producers of an API. At a point when their application becomes widely used, they need to sacrifice themselves and change their role from being artists creating beautiful APIs into responsible maintainers of their technology.

I'd argue that the API itself is beautiful, if it is real interface. If it is the right tool for making its Yours and Mine sides co-exist smoothly.

<comments/>

PS: Maybe there is more than three ways to look at an API, but I am not aware of them right now and I could not resist to use this as a tribute to one of my favorite's musical albums.