API updates

[Gary Poster]

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

On 05/29/2013 09:52 AM, John Arbash Meinel wrote:
> ...
>> 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.
> 
> I personally fully understand your request. GUI clients are quite
> a bit different, and have a lot more polling and discovering 
> functionality as a necessary part of the picture.
> 
> I know both Ian and William (and TBH myself) would prefer to
> version the API as a whole, which could give you implicit
> information about what APIs are available.

I had initially envisioned versioning the API as a whole as well, but
I don't feel that way any more.  Rather than saying pros and cons, let
me highlight a few goals I have.  I think they fall more naturally out
of versioning methods, but they can be addressed other ways.

- - It is easy to incrementally grow and change the API.
- - Devs are encouraged to actually version, and not develop perpetually
in a no-man's land "devel" version (I'm thinking of Launchpad's API here)
- - API users' code has explicit, programmatic ways of seeing whether a
particular API is available.  (Launchpad had the big WADL thing--which
I don't hold up as an implementation approach!  It did do the job
nicely though.)

That last one is the one I care most about, and related to my original
comment.  Take the rest as you will. :-)

> 
> There is a question of if it is better to support fine-grained 
> capabilities, or coarse-grained versions. (Do you support GetV2?
> vs Do you support v2 of the entire API.)
> 
> Looking at the existing RPC code, it already is using a 'func 
> methods()' to use Go's built-in type reflection to build up a map
> of what methods exist, and what parameters those methods take and
> return.
> 
> So it does already have the capabilities known as soon as you
> call: if err := conn.Serve(newStateServer(srv), serverError); err
> != nil {
> 
> 
> We have the Admin level of actions (which currently is only Login).
> It seems like you could have some sort of Admin.ListCapabilities()
> (which would only be accessible after having logged in).

Yeah, I suspect this might have been what Roger prototyped.

> 
> The only caveat is that the information is a bit disjoint, and
> even further the information about user authorization is also
> disjoint.
> 
> rpc/methods.go methodsByType will have inspected every type, and 
> determined what potential APIs are available.
> 
> However, you don't actually know if you have valid credentials on
> any of those objects until you actually try to access them. So when
> you do:
> 
> Machine("foo").DoSomething(params)
> 
> The RPC code knows that Machine is valid to call, and it knows
> that DoSomething will be a method that it can call.
> 
> However, until it actually calls Machine("foo") it doesn't know 
> whether you have rights to actually do that.
> 
> The current logic is pretty simple (requireAgent() which actually
> just means isUser.
> 
> However, one could argue that eventually that logic could grow
> complex (require that Machine("foo") only be accessed by the agent
> with authentication matching the agent of "foo".)

Right.

> I guess my statement is that the way it is currently written, it 
> should be easy to add a "list all potential APIs that are available
> in the system". However, it is not easy to have a "list all APIs
> that these credentials give me access to". And it is arguably not
> possible to give good answers for that, because you may have access
> to Machine("foo").DoSomething() but not
> Machine("bar").DoSomething.
> 
> 
> So do you care about Authorization based API discoverability? Or
> would the basic "the service implements these APIs" be sufficient
> for your use case?

As a rule, we don't want to show capabilities to a user that they do
not actually have.  That means we have the use case for
authorization-based discoverability.

That said, being able to cleanly answer the existence question would
be a great start.

Thanks again

Gary

> 
> John =:->
> 

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

iEYEARECAAYFAlGmWAsACgkQptJosaN9z//4WwCgkK3Cwf7BmScjVtajyCYbEewL
YN0An30pIbgT3onRjFlS8Kt2E9FxFZll
=1S+v
-----END PGP SIGNATURE-----