Webservice as a Stable API

[Max Kanat-Alexander]

	So, we're just about to have the basic framework for our Webservice
(our XML-RPC interface) checked-in:

	https://bugzilla.mozilla.org/show_bug.cgi?id=webservices

	One of the most valuable parts of having an XML-RPC interface is that
it allows external programs to interact with Bugzilla without having to
know the internals of Bugzilla code. It also ought to allow external
programs to interact with all Bugzillas in the same way, even different
versions of Bugzilla. (Obviously starting with 3.0 and going on.)

	An API is most useful when it doesn't change between versions. This we
call a stable API. Or, it can change, but any changes won't break old
code.

	Making a stable API is something we've never had to do before in
Bugzilla (although our Bug XML comes close), but I think it's a worthy
goal for our web service interface.

	The things required of a stable API are:

	1) A function's required parameters don't change.

	For example, if we have do_foo($foo_id), we can add an optional $reason
argument later, but we can't add any more *required* arguments to
do_foo(). So even if we allow do_foo($foo_id, $reason), we still have to
accept do_foo($foo_id).

	An interesting side effect of this has to do with *removing* required
parameters. We can remove a required parameter, but if we do, the
function's parameter list can *never* get longer without some trickery.
For example: do_bar($bar_id, $return_value) (where both are required)
becomes do_bar($bar_id). Now what if we want to add a second argument to
do_bar again? We can't, because old code will still be passing
$return_value into that second argument. (Basically, the workaround is
to use a third argument.)

	We can avoid the entire problem of removing arguments by *always* using
named parameters when there is more than one argument. Named parameters
are much easier all around, anyhow.

	2) Nothing disappears in the function's return values, and the returned
data types don't change.

	For example: we return a hash with 'foo', 'bar', and 'baz'. We cannot
ever stop returning any of those items. If 'foo' is an integer, it must
stay an integer for all of eternity. However, we could add a 'qux' item
later, because that doesn't break old code.

	3) Functions don't disappear.

	4) If anything is unstable, it's clearly noted in the docs.


	This does mean that if we mark anything as stable, it should only be
after careful review and testing. In my latest patch against the
webservice code, I've defined both STABLE and EXPERIMENTAL as ways of
describing functions, where EXPERIMENTAL means "we think it's stable but
we're still testing it out". Anything labeled "EXPERIMENTAL" should
become "STABLE" by a final release.

	My patch is here:

	https://bugzilla.mozilla.org/show_bug.cgi?id=349256

	-Max
-- 
http://www.everythingsolved.com/
Everything Solved: Competent, Friendly Bugzilla and Linux Services