Introducing Mason - a new JSON-based hypermedia format

[Jørn Wildt]

During the last few years I have been designing, discussing and building REST-ish services for real as well as for fun. All of that work has been based on some ad-hoc XML or JSON based formats both with and without hypermedia elements.

At the same time I have been looking into HAL, Siren, Collection-JSON, Hydra and (X)HTML to see if the APIs we implement at cBrain (my workplace) could be modeled satisfyingly with any of these formats. All of them could be used to some degree - but they also lack something - so I decided to design a new (generic) media type that would solve the problems I have met so far in my API carrier.

My design goals for the format has been:

- It should be purely build on JSON.

- It should be easy to adopt by both server and client developers.

- It should model both reading and writing of data.

- It should send data in JSON but also handle file uploads.

- It should be able to "speak" to client developers and help them explore services.

- It should have a generic client that allows users to interact with services (both reading and writing).

- It should feature standardized error handling.

- It should be practical and educational (but not academic) and be expressive enough to illustrate most (if not all) of the patterns we use when implementing RESTful services.

I have always liked the simplicity of HAL and send kudos to Mike Kelly for some of the ideas HAL have introduced. Mike, if your ever come by Copenhagen I'll by your a beer or two! So naturally Mason has a strong heritage from HAL.

An obvious question is "A new format? Why not build on the existing formats?". First of all because none of them cover the design goals mentioned above. Second, because I believe in evolution - Mason introduces a combination of features and design goals I haven't seen in the other formats. If developers like that they will adopt it and maybe use Mason in their next project - and over time we will see formats come and go until we eventually hit the right format. Mason is one stone on that road.

As a weak excuse for the lack of a formal specification I pledge "favoring running code over documentation". I have 1) setup an online example of a Mason based service that simulates a simple issue tracker, and 2) created a Windows based generic Mason browser for interacting with any Mason enabled service.

(the example service has quite a few annoying bugs that I will try to remove as soon as possible)

You may ask why I created a Windows based browser instead of an online version as we have seen before. The answer is simple: I am much more proficient in .NET and WPF than JavaScript and HTML. It could very well be better to create the client as a plugin to one of the browsers, but that would have been even more foreign to me. So I favored the easiest way and hope you guys have access to a Windows machine for trying out the browser.

You can find all the necessary information on GitHub: https://github.com/JornWildt/Mason. 

The format is not yet 100% stable, so I do not recommend using it for anything else than experimenting.

Feel free to download the Mason browser and start exploring the example service to get an idea of how the format is intended to work.

You are most welcome to respond to this announcement here on API-craft, but if you have questions specifically about features in Mason i suggest you use the dedicated mailing list at https://groups.google.com/forum/#!forum/mason-media-type

*** Next steps

On the very short term I have some vacation coming up, so I will probably take a small break from Mason in a few days. Then I hopefully get some feedback and ideas for improvement and be able to incorporate them.

The Mason browser needs some more features before it is practical to use (like for instance a searchable browsing history and a cancel button). Then I need to write the complete specification and improve on the example service since I want it to illustrate all the REST patterns people keep asking about.

I would also like to explore the "Stylesheets for APIs" idea I suggested a few days ago on this list.

Have fun, Jørn

(going to bed now, its way too late ...)

[mca]

once it gets stable it'd also be a good idea to register Mason at the IANA (under the vnd. tree to start), too.

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/groups/opt_out.

[Glenn Block]

Hi Jorn

I just read through the feature list. Looks straight forward with some interesting features like file-upload. Cool stuff and thanks for sharing it.

One question I have is around actions. I really like the way CJ bakes in a template for queries and for updates as it describes the data elements that you "should" send. It looks like Action in the example is a link but it doesn't have this quality of CJ. I see there's a link to a schema document, is that what you are thinking is a description of the action? Did you consider offering the ability to inline data elements for the action?

Cheers

Glenn

[Jørn Wildt]

> once it gets stable it'd also be a good idea to register Mason at the IANA

Sure.

/Jørn

[Jørn Wildt]

Glenn, 

Mason allows both schema definitions as well as templates like you mention. You can see both in action here: http://mason-issue-tracker.cbrain.net/issues/1. The "update-issue" action has a template and the "add-attachment" action uses a schema definition to generate some default data for a new attachment. You really should try it with the generic browser client: https://github.com/JornWildt/Mason/wiki/Generic-Mason-browser

My thoughts are right now:

- Schemas are optional and can safely be ignored by the client. The server may include them to guide clients, but it is not required.

- Schemas can be used to generate empty example data (but a template may be better suited to this) and also used for client side validation of input.

- Templates are optional. But I am not sure if they can be ignored by the client. The server might just have added something important to the template (for instance a one-time access token) and the client must use the template as a default value which the end user may (or may not) choose to change parts of.

- I am playing with the idea of not using templates, but instead use JSON path to point to data already in the payload. It seems exceptionally stupid to have all the API data available - and then repeat most of it in one (or more) templates. That might although just be more trouble for the client than it is worth.

/Jørn

[Austin Wright]

Why not JSON-LD or JSON Hyper-Schema?

You do seem to reference JSON-LD, actually, as "Hydra" (Hydra is an RDF vocabulary, not one I'm a particular fan of since I consider it bloated). It's RDF, which just adds the concept that links that can also point to strings, dates, and other typed data, in addition to the standard URIs. Every Link relation is also an RDF Statement. That's hardly a "completely different approach"!

JSON Hyper-Schema is my favorite: You can use Content-Type negotiation to negotiate among multiple JSON representations by using the "profile" media-type parameter:

Accept: application/json;profile=http://example.com/v1/blog.json

And that profile URI is itself the identifier of a schema, which can be used to extract link relations.

Since we're using link relations, we can describe resources in terms of things like an "error" and such (shown here as an HTTP header, which will have exactly the same meaning by definition):

Link: <http://example.com/Error>;rel="type"

So either of these solutions seems to fill all your design goals, without needing to invent a new format.

Do you find it particularly hard to use JSON in this fashion? For many applications the tooling may not quite be there yet. But we're inventing tools anyways, why not design it around existing formats?

I may respond in detail to the relevant topic later, but for a client UI, I'm working in an HTTP gateway that converts a JSON document to an HTML document using it's JSON Schema, using the JSON Schema metadata to create forms and present links. For expressive power, I don't think you can beat JSON Schema - it's practically a stylesheet for formatting into whatever end representation you wish.

Austin.

[Jørn Wildt]

> So either of these solutions seems to fill all your design goals, without needing to invent a new format.

> Do you find it particularly hard to use JSON in this fashion?

Yes, I do. Harder than simply using something like JavaScript dot-notation to access API data and links directly in JSON.

And I have looked into JSON-schema, saw the hyper-schema and weren't able to grok it in a few minutes. Apparently I'm too thick headed to use it.

The thing is; different communities are going to prefer different hypermedia enabled mediatypes. I don't believe in one-mediatype-to-rule-them-all. There are simply different preferences from different communities - and so we get different mediatypes, nothing wrong with that. The good thing is that we learn from each other; different communities means different approaches and different ideas.

/Jørn

--