Schema for Juju RPC messages

[Katherine Cox-Buday]

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