API updates

[Gary Poster]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 05/29/2013 07:24 AM, John Arbash Meinel wrote:
> Ian, William, and I discussed the changes to how we implement API 
> requests. And I think we sorted out a few points. Hopefully they
> agree that this is what we agreed on. :)

Hi John.  Thanks for writing this up.  Question or two below.

> 
> 1) The server side of the APIs should all support batch requests.
> (eg, we shouldn't have Unit.Get(one), but Units.Get([]many).)
> 
> 2) Client side, we'll still write a lot of stuff as myunit =
> client.Unit.Get(one)
> 
> As most clients will be concerned with only 1 thing 
> (Unit/Machine/Agent, etc).
> 
> 3) We aren't going to put versions into the API today. Instead, we 
> expect that when we have to update (MVU) we'll insert them to the 
> names. So something like Units.Get() will probably become
> Units.GetV2()
> 
> This will likely be versioned per-request, rather than versioning
> the API as a whole.
> 
> Lots of stuff not discussed here (how do we deprecate old things, 
> eventually removing them, etc.)

I'd like to bring up one part of that stuff.

In other conversations about versioning and new functions, we keep
trying to stick to ETAFFTP vs LBYL (as in John's email, "easier to ask
for forgiveness than permission," vs "look-before-you-leap").  That
is, if the tool prefers GetV2, there's been push back in implementing
a way to ask Juju "hey, do you implement GetV2?"  Instead, the advice
has been to simply try "GetV2" and if you get an error saying that
GetV2 is not available, you fall back.  That often works fine.

One type of scenario where this becomes shaky, to my mind, has two
components.  First, a tool (like, say, the GUI) wants to expose a
control for a new feature to the user only if the feature is actually
available in the current environment.  Second, the new feature mutates.

In a situation like this, the tool does not want to call the new
method, because it mutates.  It just wants to tell the user that it is
available as an option, without setting the user up for later
disappointment.

As has been discussed in the past, we can still follow ETAFFTP by
calling the new method with arguments that will reliably produce an
error. If Juju returns a "No method of that name" error, versus a
"wrong arguments" error, we can deduce that the method is not available.

That feels difficult to use and fragile.  I'm happy to expand on that
if requested.

As part of this versioning story, could we have a way of determining
what methods are available?  I know Roger has investigated this in the
past.

> 
> 4) API requests will generally *not* return full objects as
> responses. (eg Machine.AddUnit()[0] won't return a full
> representation of the machine with the new unit added, and the
> dirty flag changed, and whatever other records that might have been
> changed by a 3rd party)
> 
> 5) It is reasonable for the client side to update fields on the 
> in-memory structure that it knows are modified as a side-effect of
> the API it called (eg Machine.AddUnit knows to set dirty=true
> locally, even though it isn't a Machine.SetDirty call). However, it
> is expected to *not* modify fields that aren't obviously related
> (after calling AddUnit, it shouldn't have the side effect of seeing
> a new Machine.Name value.)

Will this expectation modify any existing calls?

> 
> 6) *Most* API calls are going to be field-level changes, with 
> field-level transactional guarantees, rather than object-level 
> guarantees.
> 
> eg, Machine.ChangeName(old, new) should probably take the old
> value and the new value, and do a DB transaction that asserts name
> is still old before setting it to new. However, Machine.AddUnit
> doesn't need to lock the whole Machine object in order to add a
> unit. Thus Machine.ChangeName from client A will conflict with a
> similar request from client B, but will *not* conflict with a call
> to Machine.AddUnit from client C.
> 
> 7) There will be some logic server side to handle concurrency, and 
> conflict resolution occurs in the API server as much as possible.

Big +1.

Thanks

Gary
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)
Comment: Using GnuPG with undefined - http://www.enigmail.net/

iEYEARECAAYFAlGl+7cACgkQptJosaN9z/+12ACgjDvrEPzxte2Iit5m5T84CQU6
eVAAnRVL7RBcFqdEYfKvdgv0Rf54VoId
=FRB1
-----END PGP SIGNATURE-----