I think these are the results we are looking to get out of this exercise: 1. Have a well-defined and well-documented API that third parties may consume. 2. Have a clean and well-documented Go implementation of an API wrapper which third parties may reuse. 3. Make both of these easy to find.
#1 is independent of the location of the code for the API server. No one needs to see the implementation of the server in order to be able to consume the API. They need good documentation and the IP address of the state server. If they need to care about implementation, we're doing something drastically wrong. #2 should absolutely be documented using godoc and live with the code, and have the code somewhere easily accessible in some repo, preferably without needing to download the entire juju codebase. Ideally, #1 would live at http://juju.ubuntu.com/docs/v1.18.4/API.html FWIW, I really like Roger's idea of automatically generating the API documentation from the code. On Fri, Jun 27, 2014 at 5:31 AM, roger peppe <roger.pe...@canonical.com> wrote: > On 27 June 2014 10:05, William Reade <william.re...@canonical.com> wrote: > > I think one of the biggest problems is the naming: state/api is a hackish > > and minimal api client implementation, while state/apiserver is where the > > actual api is defined... except the params package, which for some reason > > lives under state/api. > > > > I think the most important actions are: > > > > * move state/api/params under state/apiserver > > * move state/apiserver to the top level, and make sure it's clearly > > documented > > Why would we want to do that? No non-juju package should ever > be running the API server or calling any of its code directly, should it? > Someone connecting directly to the API and sending JSON > should not need to look at godoc package documentation > to infer what their messages should look like. > > I agree that the API should be fully documented, and that > the current api package does not expose some capabilities > of the underlying API implementation, notably the ability > to make "bulk" calls (although in practice there's no advantage > to doing that currently). > > However that's an argument for a) fully documenting the API > and b) updating the API client side to more closely reflect > the actual API. > > I have long thought that it should not be too hard to generate > API documentation automatically from the server-side code. > This was part of the original motivation for the rpcreflect package. > I have code that generates JSON description of all the > calls in the API - if integrated with comments from the > server-side implementation methods, I think this > could be pretty good, and avoid the need to maintain > a separate API doc. > > Likewise the client side code can be automatically generated > (I have done that before too), which would make for a Go > API interface which exactly reflected the server side. > > As John says, api/params is an important part of the client-side > interface - it defines the data structures that the server and client > side have in common. > > cheers, > rog. > > > > > Then I'd be keen to separate the internal api client code from the > external > > one; and at that point I'd be happy to move the external api client code > > into its own repo. There's no disadvantage to having that code external, > > because we can't afford to break our external api clients regardless; for > > the internal ones we have more power and control, because we're the only > > ones who have to deal with the impact of change. > > > > (This would then involve separating the protocol-level code out somewhere > > *else*, so that we could reuse it both internally and externally; and > we'd > > probably want both the server and client protocol parts together; but I > > think that the point where we can reasonably move a package outside the > main > > repo is some way away regardless, so I'm not keen to focus on it at the > > moment.) > > > > Cheers > > William > > > > > > > > On Fri, Jun 27, 2014 at 10:01 AM, roger peppe <roger.pe...@canonical.com > > > > wrote: > >> > >> On 27 June 2014 07:51, David Cheney <david.che...@canonical.com> wrote: > >> > On Fri, Jun 27, 2014 at 4:21 PM, John Meinel <j...@arbash-meinel.com> > >> > wrote: > >> >> Just my quick thought, I think moving it out from "state/api" into > just > >> >> a > >> >> top level "api" would be reasonable and a lot less clumsy than > trying > >> >> to > >> >> pull it out into an entirely separate repository. > >> > > >> > +1 > >> > > >> > I don't think the api package is useful outside Juju (at this time) > >> > and splitting it into another repo just doubles the amount of work. > >> > >> Do you mean that the API package isn't useful *from* outside Juju, > >> or that the API package isn't useful *independently of* Juju? > >> > >> If the latter, I totally agree (the whole point is that it integrates > with > >> Juju) > >> but if the former, I disagree. If we are to allow any external Go > programs > >> that use Juju (and I think we should - we should act as good citizens > >> in the Go ecosystem) then the API package is the only way to do it. > >> We shouldn't force people to write their own API interface just because > >> we're not prepared to support our own. > >> > >> BTW, I think it would be a good idea to split off the agent parts of the > >> API > >> from the client parts - the former should not be considered public. > >> > >> -- > >> Juju-dev mailing list > >> Juju-dev@lists.ubuntu.com > >> Modify settings or unsubscribe at: > >> https://lists.ubuntu.com/mailman/listinfo/juju-dev > > > > > > -- > Juju-dev mailing list > Juju-dev@lists.ubuntu.com > Modify settings or unsubscribe at: > https://lists.ubuntu.com/mailman/listinfo/juju-dev >
-- Juju-dev mailing list Juju-dev@lists.ubuntu.com Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju-dev
