Announcing Mason

[Jørn Wildt]

(This is a cross copy from the API-Craft mailing list)

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.

*** 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.

Have fun, Jørn