+1 On Wed, Jul 27, 2016 at 9:52 AM, Katherine Cox-Buday < [email protected]> wrote:
> > I am a huge fan of publishing schema's and then generating SDKs and > documentation websites off of them. It brings your API closer to language > agnostic, removes the burden on us having to hand-craft both our API client > and our documentation site, and makes validation implicit. I'm not up on > what the best tools for doing this are, but Swagger[1] seems to be popular. > > [1] - http://swagger.io/ > > John A Meinel <[email protected]> writes: > > > We've had some requests from people trying to drive Juju that it would > > actually be really nice if we were stricter with the messages that we > > accept on our API. Specifically, as we've changed the API methods, > > they had several hard-to-debug problems because they were passing a > > parameter that was named incorrectly, and Juju was not giving them any > > indication that something was wrong. > > > > I put together a (very hackish) test branch, to see if I could use > > JSONSchema to define our request and response messages, and give nicer > > error messages (rather than silent acceptance). As I was working with > > JSON, I realized the extra " and { characters really got in the way of > > making a document that was readable, so I leveraged our existing YAML > > to JSON conversion mechanisms to write the description in YAML and > > then load the object tree into JSONSchema to validate our requests. > > > > I did end up getting basic validation of the outer structure (just the > > Request/Response message, not the contents of Parameters) functioning > > here: > > > https://github.com/jameinel/juju/blob/yaml-schema-rpc/rpc/jsoncodec/codec.go > > You can see what some of the error messages look like here: > > > https://github.com/jameinel/juju/blob/yaml-schema-rpc/rpc/jsoncodec/codec_test.go > > > > The actual code itself isn't useful as is, because it needs to have > > the schema validation stuff pulled out into its own file, etc. But it > > does give a proof-of-concept of basic message validation. I'm not > > super excited by some of the error messages > > (gojsonschema.ResultError.Description is very nice by itself for > > missing keys, extra properties, etc, but not enough information for > > invalid values, while ResultError.String() is overly verbose in the > > opposite way.) > > > > I'd like to get a bit of feedback on whether people would find this > > interesting, especially if we brought that all the way into the Param > > structs as well. I haven't done any benchmarking to determine if this > > is a large overhead or not. But the golfing community seems determined > > to not do a Strict Unmarshal function, and seems to be recommending > > using a Schema instead. > > > > I'm not completely sold either way, though I do find the YAML format > > for the schema description to be far more human readable than the JSON > > format. > > > > Thoughts? > > > > John > > =:-> > > -- > Katherine > > -- > Juju-dev mailing list > [email protected] > Modify settings or unsubscribe at: > https://lists.ubuntu.com/mailman/listinfo/juju-dev > -- Reed O'Brien ✉ [email protected] ✆ 415-562-6797
-- Juju-dev mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju-dev
