Schema for Juju RPC messages

Reed O'Brien reed.obrien at canonical.com
Wed Jul 27 17:43:36 UTC 2016


+1

On Wed, Jul 27, 2016 at 9:52 AM, Katherine Cox-Buday <
katherine.cox-buday at canonical.com> 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 <john.meinel at canonical.com> 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
> Juju-dev at lists.ubuntu.com
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/juju-dev
>



-- 
Reed O'Brien
✉ reed.obrien at canonical.com
✆ 415-562-6797
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20160727/421f435d/attachment.html>


More information about the Juju-dev mailing list