API updates

[John Arbash Meinel]

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

...
> 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.

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).

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".)


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?

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.13 (Cygwin)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iEYEARECAAYFAlGmCCwACgkQJdeBCYSNAAOwYQCfTfKH1cSlu3elyOQQee4hf3uW
96oAoK9/fLr6ZfNKCW7iQYOW5Brd3K0T
=BQvO
-----END PGP SIGNATURE-----