Why did you adopt Mason?

[Martin Bayly]

Mason doesn't seem to have the same level of adoption as other hypermedia types!

There are a few posters on here who seem to have adopted it none the less (I've read Curtis Farnham's blog about why they used it).

Just interested to understand the reasons why others chose it in the face of the more apparent popularity of some of the other types.

I'm working on a new public facing API and just getting buy in to use hypermedia might be difficult - but choosing a less well known hypermedia type even if its the best for our purpose might be doubly difficult.

(Sorry, Jorn - must be a catch-22 for you right now!)

Thanks for any insights.

Cheers

Martin

[Kijana Woodard]

[Disclaimer: I've never implemented Mason]

I went to a talk last night by Mike Amundsen. He said something that I think is relevant to your issue: "Don't bet your business on a format".

In other words, you should arrange your code such that the format choice is replaceable. 

If Mason meets your needs, use it. 

If someone comes along and demands Siren, calculate whether adding Siren support is "worth it", and add that too.

Even though HAL is "the most popular format", most developers won't show up with a generic HAL client and complain that they can't talk to your API. I would wager that you could not mention the media type at all and jut explain how to code against it [gists?] and people would be fine with it [as fine as with any hypermedia format]. 

--
You received this message because you are subscribed to the Google Groups "Mason media type" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mason-media-ty...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Curtis Farnham]

When you say "hypermedia", what exactly are you referring to?  Let me take some stabs in the dark here...

Finding or building an API client that uses the HATEOAS principle (start with the homepage, media types are known ahead of time, and it browses the API's link structure until it finds what it wants) is a fool's errand.  Maybe things have changed in the last 6 months since I last spent time digging, but this has always been a sticking point within the REST community since a proper HATEOAS client is vastly more complicated to write than one which hard-codes more details such as URL paths.

But the huge advantage I see to building an API that supports it anyway is that the API becomes more or less self-documenting.  The developer *is* your HATEOAS client, ha ha.  If your API only theoretically needs its clients to know your base URL and the media types you offer, and you provide all the links and forms right there inline with your data, then the developer who is building code on top of your API receives a tremendous benefit.  It minimizes how much you have to document things, and it speeds up their ability to integrate with your API.  This directly translates to your company's bottom line, since it promotes adoption of your API and minimizes your support costs.

If the people you are trying to sell the idea to are nontechnical, it might not be helpful to try to also sell the idea of Mason or some other format to them at the same time.  Just emphasize the financial benefits of having a self-documenting API, lowering the barriers to adoption, etc.  Leave the technical discussion of "hypermedia" and the question of the format for another day.

[Martin Bayly]

Yeah, I would agree that we shouldn't be betting our business on a format and this is only the API (most of the real complexity is below it) and I feel like I'm bikeshedding (as the designers of JSON API would say) in just spending all this time looking at different hypermedia types.

We've started to have a similar discussion internally, where the comment has been made that the hypermedia type is just a last second 'transform' so you should easily be able to switch it out.  But I'm not convinced is is that simple yet.  I see that there is a huge difference between types like Uber and JSON API.  Mike A promotes the idea of building APIs around non-structured data which is why types like Uber and Collection+JSON promote very generic data structures (just name/pairs like a Web form).  Mike A warns against using adhoc JSON/XML in hypermedia types/APIs. I think if you use generic data structures everywhere it's probably easier to interchange.  On the contrary types like JSON API, JSON-LD/Hydra and Mason promote being able to use highly structured data for both safe and non-safe operations.  Siren sits somewhere in the middle. This is one of the primary reasons that Jørn gives for creating Mason.

I see there being a lot of implementation differences between using generic vs structured data for setting up operations in the code.  Yeah, it's not rocket science to convert between the two or migrate your code from one approach to the other but I'd rather spend my time on other things.

Cheers

Martin

[Martin Bayly]

When I say hypermedia I'm referring to all the Hypermedia constraints described in the book RESTful Web APIs.  I'm trying to drink the cool-aid, I've always found it too bitter when I've looked at following hypermedia constraints before.

I would agree that writing a proper HATEOAS client is vastly more complicated than writing one which uses more traditional hard-coded API constraints.

I'm not really interested in building or supporting generic clients, but I am interested in providing APIs that minimise the amount of out of band information that is needed to communicate with the APIs by both our own client applications and 3rd party users of our APIs and that allow us to evolve our APIs without complicated versioning strategies.

Yeah, I'm not trying to sell Mason to any non-technical people.  I agree that just selling hypermedia is sufficient. The Mason argument will be a hard sell for our other technical people though.

Cheers

Martin

[Kijana Woodard]

We also talked about this notion of switching between formats. You're right, some concepts are not representable in all formats.

What I like about HAL and Mason is that they are relatively simple. That makes them easier to reason about, easier to explain, and easier to implement for both server and client. 

It is desperately easy to spend unlimited time thrashing on nuances [1]. If you're attracted enough to Mason to post this, I'd say start with it and see how things go.

What's the worse case scenario? You have to completely change formats?

The reality is you're probably going to be using another format in 10 years anyway. SOAP anyone?

[1] https://en.wikipedia.org/wiki/Parkinson%27s_law