Schema for Juju RPC messages

[Rick Harding]

On Wed, Jul 27, 2016 at 3:18 PM Katherine Cox-Buday <
katherine.cox-buday at canonical.com> wrote:

> Good point, Mark. I agree that it's difficult to make an auto-generated
> client idiomatic/nice to use. What I like to do is use the schema to
> auto-generate the boilerplate, and then wrap that with a small shim that is
> more crisp.
>
> Do you have an opinion on this approach?


I think that using a schema to help generate useful documentation and
improved error messaging/API input validation when the API isn't used
correctly (as in the case of what drove John to chase this down originally
[1]) is great and awesome. It keeps docs in sync with reality and forces us
to focus on the naming and thoughtfulness of the API since future work is
generated from the actual code. We don't get to fake it.

However, an API client in any language should never be auto generated.
Languages are unque and value different things. An API client is all about
taking a given API, and mapping it to the ideas and constructs a language
values. For instance, a python client for an API would not expect to expose
to users of that client HTTP error codes. They'd expect those to get mapped
to proper exceptions that mean something in Python to the user. A
JavaScript API would expect to have the API mapped to data types and other
constraints that JS present that won't make sense for other languages.

On top of that, clients are meant to be used by users farther down the
pipe. The API calls themselves are meant to be used by a few client
authors. Those client authors are intended to provide abstractions,
shortcuts, and workflows that may span multiple API calls to the end user.
Imagine an API that takes three steps to login. API clients should work
hard to map those to a single API client function call, internalizing the
complexity of the API so that the broad user base of the client does't have
to deal with that complexity.

There's no way to auto generate a client that does these helpful and
necessary simplifications across a given API automatically.

That being said, any API client that requires three API calls to login
should be beat over the head with a fail stick, but there are many cases
where performing some workflow might require multiple api calls. The API
clients should work out a single function of "doSomethingAwesome(param1,
pararm1)" when it's in fact performing multiple API steps because it makes
sense for end users, or I guess developers in this case.

1: https://bugs.launchpad.net/juju-core/+bug/1585289
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20160728/83ef631b/attachment-0001.html>