[[Category:APIDesignPatterns:Anti]]

[[Category:APIDesignPatterns:Anti]]

[[Category:APIDesignPatterns:Encapsulation]]

[[Category:APIDesignPatterns:Encapsulation]]

<comments/>

<comments/>

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 [[URL]]s valid forever), but still the knowledge of proper [[API]] design may become an advantage.

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 [[URL]]s 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 a consumer: Beware of ''version lock-in''. Beware of the ease of use of [[API]]-less [[API]]s. It is tempting and easy to cross the [[wikipedia::Rubicon|Rubicon]], but once you are there, there may be no way to upgrade your server, except start completely new one.

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 [[API]]s. It is tempting and easy to cross the [[wikipedia::Rubicon|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''.

Good luck learning to recognize well maintained [[API]] frameworks! Only those will help you with smooth [[upgradability]] and prevent the ''version lock-in''.

=== Need API on server? ===

=== Need API on server? ===

Some readers of [[TheAPIBook]] say that it is nice, but not really useful for them as they mostly developer server side end user applications. True, there is not much necessity when generating [[HTML]] pages (maybe except keeping [[URL]]s valid forever), but still the knowledge of proper [[API]] design is important.

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 [[URL]]s 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 a consumer: Beware of ''version lock-in''. Beware of the ease of use of [[API]]-less [[API]]s. It is tempting and easy to cross the [[wikipedia::Rubicon|Rubicon]], but once you are there, there may be no way to upgrade your server, except start completely new one.

Not from point of view of [[API]] producer, but from view of a a consumer: Beware of ''version lock-in''. Beware of the ease of use of [[API]]-less [[API]]s. It is tempting and easy to cross the [[wikipedia::Rubicon|Rubicon]], but once you are there, there may be no way to upgrade your server, except start completely new one.

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.

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, then risked the upgrade.

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. As [[upgradability|upgrade]] is as painful as switch to other system, there is no reason to stick with you as a provider of the original solution.

Moral of this story? When you have an [[API]]-less system, you cannot build loyal customers. When [[upgradability|upgrade]] is as painful as switch to other system, there is no reason to stick with you as a provider of the original solution.

 

Btw. when my friend realized the loose/loose situation, he'd rather left.

=== Need API on server? ===

=== Need API on server? ===

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.

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). When this become known, customers rather suffered painful switch to different software, then risked the upgrade.

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, then risked the upgrade.

Moral of this story? When you have an [[API]]-less system, you cannot build loyal customers. As [[upgradability|upgrade]] is as painful as switch to other system, there is no reason to stick with you as a provider of the original solution.

Moral of this story? When you have an [[API]]-less system, you cannot build loyal customers. As [[upgradability|upgrade]] is as painful as switch to other system, there is no reason to stick with you as a provider of the original solution.

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.

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 needs. 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.

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). When this become known, customers rather suffered painful switch to different software, then risked the upgrade.

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). When this become known, customers rather suffered painful switch to different software, then risked the upgrade.

=== The Economic Side ===

=== 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 competitors than asked the original company to perform an upgrade.

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.

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.

I faced the problem of an ''upgrade'' when I finished my [[ReCaptchaArticleComments|ReCAPTCHA support for article comments extension]]. The [[MediaWiki]] provides two [[wikipedia::Captcha|Captchas]] - basic simple arithmetic question and [[wikipedia::ReCaptcha|ReCaptcha]]. I developed, and debugged my code against the simple one and then just hoped the [[wikipedia::ReCaptcha|ReCaptcha]] will work automatically. [[wikipedia::ReCaptcha|ReCaptcha]] is subclass of basic [[wikipedia::Captcha|Captcha]], so using it instead of the original, shall be without any issues, shalln't it?

I faced the problem of an ''upgrade'' when I finished my [[ReCaptchaArticleComments|ReCAPTCHA support for article comments extension]]. The [[MediaWiki]] provides two [[wikipedia::Captcha|Captchas]] - basic simple arithmetic question and [[wikipedia::ReCaptcha|ReCaptcha]]. I developed, and debugged my code against the simple one and then just hoped the [[wikipedia::ReCaptcha|ReCaptcha]] will work automatically. [[wikipedia::ReCaptcha|ReCaptcha]] is subclass of basic [[wikipedia::Captcha|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 [[wikipedia::Captcha|Captcha]] superclass, was completely broken with [[wikipedia::ReCaptcha|ReCaptcha]] subclass. The ''upgrade'' was not painless at all. Why? Because I called some private method in the [[wikipedia::Captcha|Captcha]] which had no meaning in the [[wikipedia::ReCaptcha|ReCaptcha]]. At least I guess it was private implementation method, as in the [[MediaWiki]]'s world of [[API]]-less [[API]]s, 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.

That would be too ideal! Of course my code which was OK with [[wikipedia::Captcha|Captcha]] superclass, was completely broken with [[wikipedia::ReCaptcha|ReCaptcha]] subclass. The ''upgrade'' was not painless at all. Why? Because I called some private method in the [[wikipedia::Captcha|Captcha]] which had no meaning in the [[wikipedia::ReCaptcha|ReCaptcha]]. At least I guess it was private implementation method, as in the [[MediaWiki]]'s world of [[API]]-less [[API]]s, one cannot be sure. It was a method and there are no [[ClarityOfAccessModifiers|access modifiers]], so one cannot tell... Oh, lord, please never force me upgrade whole [[MediaWiki]] installation! Thanks.

=== The Economic Side ===

=== The Economic Side ===

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 [[upgradability|upgrades]], please. Bug fix only as minimally as possible!

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 [[upgradability|upgrades]], please. Bug fix only as minimally as possible!

I faced the problem of an ''upgrade'' when I finished my [[ReCaptchaArticleComments|ReCAPTCHA]] support for article comments extension]]. The [[MediaWiki]] provides two [[wikipedia::Captcha|Captchas]] - basic simple arithmetic question and [[wikipedia::ReCaptcha|ReCaptcha]]. I developed, and debugged my code against the simple one and then just hoped the [[wikipedia::ReCaptcha|ReCaptcha]] will work automatically. [[wikipedia::ReCaptcha|ReCaptcha]] is subclass of basic [[wikipedia::Captcha|Captcha]], so using it instead of the original, shall be without any issues, shalln't it?

I faced the problem of an ''upgrade'' when I finished my [[ReCaptchaArticleComments|ReCAPTCHA support for article comments extension]]. The [[MediaWiki]] provides two [[wikipedia::Captcha|Captchas]] - basic simple arithmetic question and [[wikipedia::ReCaptcha|ReCaptcha]]. I developed, and debugged my code against the simple one and then just hoped the [[wikipedia::ReCaptcha|ReCaptcha]] will work automatically. [[wikipedia::ReCaptcha|ReCaptcha]] is subclass of basic [[wikipedia::Captcha|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 [[wikipedia::Captcha|Captcha]] superclass, was completely broken with [[wikipedia::ReCaptcha|ReCaptcha]] subclass. The ''upgrade'' was not painless at all. Why? Because I called some private method in the [[wikipedia::Captcha|Captcha]] which had no meaning in the [[wikipedia::ReCaptcha|ReCaptcha]]. At least I guess it was private implementation method, as in the [[MediaWiki]]'s world of [[API]]-less [[API]]s, 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.

That would be too ideal! Of course my code which was OK with [[wikipedia::Captcha|Captcha]] superclass, was completely broken with [[wikipedia::ReCaptcha|ReCaptcha]] subclass. The ''upgrade'' was not painless at all. Why? Because I called some private method in the [[wikipedia::Captcha|Captcha]] which had no meaning in the [[wikipedia::ReCaptcha|ReCaptcha]]. At least I guess it was private implementation method, as in the [[MediaWiki]]'s world of [[API]]-less [[API]]s, 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.