API updates

[Tim Penhey]

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

On 30/05/13 00:28, Ian Booth wrote:
> On 29/05/13 21:24, John Arbash Meinel wrote:
>> 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.)
> 
> Part of me still wishes that the API version be embedded in the
> request to keep the method names "clean". I'd like to think we can
> still discuss this when the time comes to implement it.

+1 on that idea

>> 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)
> 
> 
> I disagree with this approach but sadly for me may have lost the
> argument here. Given we are not implementing a fully stateless
> design, the potential for stale data to cause issues is real, and
> complicates the programmimg model. We can alleviate this somewhat
> by API requests returning the full objects as responses. The added
> overhead is not high - a few bytes on the wire. We are making a
> round trip anyway to invoke the API, and the API returns some data
> to the caller eg error/success. So it is not too unreasonable to
> augment the returned data with the new object state.

I have to admit that I agree with Ian here.  What is the cost of us
implementing this?  I think that should be compared with the cost of
not implementing it.  Particularly in relation to point 5.

Is it reasonable to have the API caller specify if they want a full
representation back?

>> 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.)
> 
> 
> I have a real problem with this. If by "client side" you mean
> remote object in a distributed system sense of the word, that means
> we are having to write the same state manipulation logic in 2
> places - the client proxy and the server in-memory model. The
> client has no right to know what fields it needs to update as a 
> result of calling an API - that's the service's job. And it becomes
> moot if we return the new object state when we make an API call.
> See point 4 above.

William wrote:
> Just to expand on this: this is the model used by the state
> package, and we've got a bunch of code written with these
> assumptions in
mind, > so fixing this will be very costly; certainly, I think, more
so than > duplicating the update-a-few-fields style of the existing
state code.


Using current code debt as a reason not to make something better seems
spurious.  If it is hard to fix now, it will be harder later.

Is there a way that we can provide correct behaviour without
invalidating all the existing code?

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

iEUEARECAAYFAlGmnXYACgkQd1fvI4G7WRBdsACgkdqcbXnVuamm+prCHl+jeowt
JKAAlR++6z1DPvp1KBt5TuAGsx27hsM=
=Q9BS
-----END PGP SIGNATURE-----