Hear, hear -- all for locked down APIs and strict versioning. :) +1
Aral
Sent from my iPhone
On 2 Apr 2010, at 17:02, Isaiah Carew <[email protected]> wrote:
A while back I was frustrated with an OS library method that had a
well known quirk that never got fixed. When I cornered an engineer
at a dev conference he told me something profound: Once an API has
been released it's locked in. It's being used by tens of thousands
of apps and millions of users. Changing the behavior in any way,
even to improve it, is likely to hurt more than it helps.
Last night Twitter added a new field to the search results. I use a
publicly available JSON parser bolted on to MGTwitterEngine (both
popular choices, I think), it had an odd trigger for detecting an
early end of the Results dictionary and trying to fail gracefully.
The new field triggered this condition. In other words, the lib
author made a bad assumption. Fortunately a very easy bug to find
and correct (even at 2am).
However, it brings me to my point: that the search results *did*
change. They are to spec of course, and the JSON lib *should* have
been flexible. But it wasn't. And there was little chance of
anyone finding out until it affected everyone using my software.
For once, I was grateful that I only have a few thousand users.
But, doesn't every change have this potential? The potential of
triggering a well hidden bug in a client that **is** popular and be
hugely catastrophic. Am I wrong in thinking this?
To make this critique a bit more constructive I'd offer some
suggestions of what I see in other popular API:
1. Every change must be opted into or deprecated away.
2. Deprecation periods need to last for months, not days.
3. Version the endpoints to allow for a one-shot way to know which
behavior to expect.
4. Document the version differences in the API docs.
5. Add a sandbox for clients to test new endpoints or new changes
in a safe way.
isaiah
http://twitter.com/isaiah
--
To unsubscribe, reply using "remove me" as the subject.
