On Wed, Jul 27, 2016 at 3:18 PM Katherine Cox-Buday < katherine.cox-bu...@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
-- Juju-dev mailing list Juju-dev@lists.ubuntu.com Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju-dev
