APILessAPI
From APIDesign
Can you imagine world without an API? I can now. This website is powered by MediaWiki and from time to time I need to improve it to better suite its users needs, to prevent spam, etc. Recently I integrated preview mode for mp3s (so now we really have MediaWiki and not only pictures wiki) and I also integrated Captcha and ReCAPTCHA with the article comments extension. Both these experiences made me realize some gotchas related to living in API less world.
Contents |
Edit the Source
The usual style to work with MediaWiki is to download its release, unzip it and get its sources into some disk folder. Whenever your want to configure the system or to install some extension, one of the necessary steps you have to do is to edit some source file. There are some best practices and well-known files that are designed to be edited, however not all tasks can be achieved by sticking to these files. As far as I can tell in order to change the site skin (to white on black which few people love and many hate) one has to cross the Rubicon and edit files that are not so well-known.
I am trying to express two claims:
- editing sources is essential part of using the API of MediaWiki
- there is no enforced boundary between the well-known files and the less known ones
As a result what starts as expected use of the API - e.g. editing local settings configuration file, may soon grow beyond anything expected by the MediaWiki developers. This is inevitable, there is no sharp boundary and just a minimal warning to notify you are on the edge and that just with one more step you end up on the other side.
Fear of Upgrades
You might say: "So what? I do not need a boundary, this feels much more comfortable". You'd be right. At least in the initial stage. This is more comfortable, one does not need to use a "blackbox" (as APIs always cover what is inside something). One has full access and can tweak the whole system to fit own needs without any restrictions. So far so good.
However this has its dark side. In the long term and as the number of various modifications increases, you are more and more locked in. In my case of MediaWiki, it is not vendor lock-in, but version lock-in. I am afraid that I will never be able to upgrade to new version. Because if I try, I will need to apply all my changes once again to it. Although I keep them all versioned in my mercurial repository, it is almost certain that some of my changes are too hardcore and will not be backportable.
Can you estimate the chances of upgrading to new version of MediaWiki, applying my changes and getting into state that works? Well, that would be like letting two people massage an Amoeba randomly for few years hoping they will end up in the original state. Obviously this is not going to happen. Keeping BackwardCompatibility when you are not shielded by an API boundary is impossible. This would require another level of BackwardCompatibility - a diff compatibility. Of course, everyone who ever applied patch and had to resolve conflicts, knows there is just one way to be diff compatible - don't change a single line!
Wanna upgrade?
I guess now I understand why nobody upgrades running servers. In API-less world where everyone can patch everything and there is no way to hide implementation details behind the API facade, there is no other chance. What is once built up, needs to run till the end of its days. No upgrades, please. Bug fix only as minimally as possible!
I faced the problem of an upgrade when I finished my ReCAPTCHA support for article comments extension. The MediaWiki provides two Captchas - basic simple arithmetic question and ReCaptcha. I developed, and debugged my code against the simple one and then just hoped the ReCaptcha will work automatically. ReCaptcha is subclass of basic Captcha, so using it instead of the original, shall be without any issues, shalln't it?
That would be too ideal! Of course my code which was OK with Captcha superclass, was completely broken with ReCaptcha subclass. The upgrade was not painless at all. Why? Because I called some private method in the Captcha which had no meaning in the ReCaptcha. At least I guess it was private implementation method, as in the MediaWiki's world of API-less APIs, one cannot be sure. It was a method and there are no access modifiers, so one cannot tell... Oh, lord, please never force me upgrade whole MediaWiki installation! Thanks.
The Economic Side
A friend of mine got very hard task one day: His company product started to loose against competitors ones. There were a lot of installations of the software, however customers rather switched to competitor offerings than asked the original company to perform an upgrade.
Was the company unable to produce better version? No, not at all. My friend had better version available. But it was not at all easy to install it. Was the new version so incompatible? No, it was almost absolutely compatible to the original pristine version.
There was just one problem: No customer had a pristine version. When such version was first installed, a consultant was "sold with it" - e.g. few experts needed to tweak the code to make it run on the customer site. The similarity with my MediaWiki example is in almost no formal API being specified. Thus the consultants edited everything, schema of databases, core classes, etc.
Obviously keeping compatibility with unknown modifications done by hundreds of such consultants is impossible. As a result any attempt to upgrade to new version failed (regardless of a consultant being "sold with it" for few weeks again). When this become known, customers rather suffered painful switch to different software, than risked the upgrade.
Moral of this story? When you have an API-less system, you cannot build loyal customers. When upgrade is as painful as switch to other system, there is no reason to stick with you as a provider of the original solution.
Need API on server?
Some readers of TheAPIBook say that it is nice, but not really useful for them as they mostly develop server side end user applications. True, there is not much necessity to keep compatibility when generating HTML pages (maybe except keeping URLs valid forever), but still the knowledge of proper API design may become an advantage.
Not from point of view of API producer, but from view of a consumer: Beware of version lock-in. Beware of the ease of use of API-less APIs. It is tempting and easy to cross the Rubicon, but once you are there, there may be no way to upgrade your server, except start completely new one.
Good luck learning to recognize well maintained API frameworks! Only those will help you with smooth upgradability and prevent the version lock-in.
<comments/>
research paper writing services
Follow
