The one true media type

[Mike Kelly]

Moving this to another thread

On Thu, May 24, 2012 at 9:31 PM, Mike Schinkel <mi...@newclarity.net> wrote:
> On May 24, 2012, at 4:10 PM, Mike Kelly wrote:
>> Do you have any specific reservations about hal+json?
>>
>> Our google group is relatively active, there's a bunch of open source
>> libraries for it, the type media itself was designed to be realistic
>> and minimal in its scope.
>
> My reservations are not about the spec, they are about the fact that not everyone on this list agrees that HAL is the one way to do hypermedia in REST.  Duncan Craig thinks it should be Object Network. And Arlo Belshee thinks it should be OData. Mark Nottingham thinks is should be home-json. And who knows who else has other ideas they are advocating.
>
> For HAL it's the fact that there's one only author on the spec[1] (you), the fact that no major company has signed on the support HAL as an author, there has been no working group assemble to reconcile concerns that people who are not you may raise.
>

The spec is on github, anyone is free to fork it and raise a pull
request. Afaik, there's a relatively large organisation using HAL in a
30+ dev project to replace their legacy system, there are various
others who are using it and have been for a while now.

There is a 'working group' - it's the 80+ people on the google group
mailing list who raise issues and receive emails from me asking for
feedback on new features/changes I'm making.

> Mike regarding HAL none of this is really your fault and most is beyond your control.  I'm simply saying IMO that until we have a true *standard* that hypermedia on public APIs causes more harm than good.

I disagree, I can't see any significant chance for 'harm' - I think
(hopefully) the fittest will survive and we'll end up with the best
option(s) left standing.

> One clear way to change it is to bring interested parties together, reconcile down to one (1) spec and publish it as an RFC with a goal to establish a standard.

With respect that is incredibly nieve, there are many different views
about how such a type should look it's unlikely that such a committee
of conflicting view points would come to any agreement on anything. I
think the way it works now is ok, each individual author/community
publishes their design and tries to generate some traction - once some
decent traction is reached then I think it makes sense to look towards
fancy (painful) things like writing specs for RFCs and setting up
'proper' working groups. Fwiw, I think HAL is getting to the stage
where it makes sense to write a proper spec aimed at becoming an RFC,
if you or anyone sharing this point of view is interested then please
join hal-discuss on google groups as this is likely where I will be
looking for input on this.

Cheers,
M

[Mike Schinkel]

The spec is on github, anyone is free to fork it and raise a pull
request. Afaik, there's a relatively large organisation using HAL in a
30+ dev project to replace their legacy system, there are various
others who are using it and have been for a while now.

There is a 'working group' - it's the 80+ people on the google group
mailing list who raise issues and receive emails from me asking for
feedback on new features/changes I'm making.

I mean "official" working group sponsored by W3C or IETF?  IMO there needs to be a body to sanction it.  

HTML because a widely used standard without lots of competing alternatives because of the standardization process that W3C arose to provide for HTML. HAL will be just another person's approach until there is a group that comes together to standardize it.

 

I disagree, I can't see any significant chance for 'harm' - 

The harm is in how hypermedia can impede adoption for a public API.

It's really easy to compose a URL and easy to CURL that URL but it's harder for a lot of web developers to go beyond that.

I think
(hopefully) the fittest will survive and we'll end up with the best
option(s) left standing.

Without active management it's unlikely because few people are currently motivated to use hypermedia. Beyond the REST true believers most people don't see the benefits (and I say "most" based on empirical evidence of percent of public APIs that don't support URL construction.)

With respect that is incredibly nieve, there are many different views
about how such a type should look it's unlikely that such a committee
of conflicting view points would come to any agreement on anything.

There were many, many conflicting views about what HTML5 should contain but because they knew there was value to only 1 HTML the stakeholders agreed to make only 1 spec.

Looking back on the original HTML, I feel strongly we would not have had a web had a bunch of different people all decided to create something like HTML and all start publicly advocating for people to use their version. Instead TBL designed HTML and promoted it when nobody else had the vision, and fortunately he got HTML evolved enough before companies started trying to take control of it, and then he created the W3C to allow collaboration with those stakeholders and subsequent establishment of standards (yes, I've simplified things, but the point is the same.)

REST hypermedia is currently still-borne for public APIs because nobody is currently actively reconciling the various visions that different advocates have.

I think the way it works now is ok, each individual author/community
publishes their design and tries to generate some traction - once some
decent traction is reached then I think it makes sense to look towards
fancy (painful) things like writing specs for RFCs and setting up
'proper' working groups.

I agree that's the natural evolution and that we might eventually evolve to a standard.  But it won't happen quickly if nobody actively pushes for reconciliation.

So in the mean time we need people like me to say: "Wait, hypermedia ain't the panacea you may have heard, at least not for public APIs."  If ya'll are okay with me pointing that out to new posters on the list, then it's all good. :)

Fwiw, I think HAL is getting to the stage
where it makes sense to write a proper spec aimed at becoming an RFC,
if you or anyone sharing this point of view is interested then please
join hal-discuss on google groups as this is likely where I will be
looking for input on this.

I'd be highly interested, but since working on a spec wouldn't generate revenue for my consulting business given our current focus I unfortunately can't spend any more time than an occasion comment on this list.  Even though I wish I could be more involved.

-Mike

[Daniel Roop]

So there seems to be a good set of people who care about this topic on this group.  Why don't we band together and try to create something?  Between the REST academics like mca, mike kelly and myself and the Pragmatic API Developers like Mike Schinkel, Brian Mulloy etc..  we should be able to create something useful.

The good thing is most of what we have all been doing independently is circling around the same target, best I can tell.

To be clear I don't actually think there can be one content-type to rule them all (I actually believe that is anti REST) but I do believe for JSON there can be a common base they all extend (think like Atom links for XML) with common concepts that can be shared among all other formats that want "hypermedia" embedded in them.

I have never participated in a RFC committe or Working Group.  Has anyone here done it?  I briefly read the IETF rules and it basically says you need an interested group of people to prove enough interest and IETF will support the creation of a charter.

Thoughts?

[Mike Schinkel]

On May 24, 2012, at 10:10 PM, Daniel Roop wrote:

To be clear I don't actually think there can be one content-type to rule them all (I actually believe that is anti REST) but I do believe for JSON there can be a common base they all extend (think like Atom links for XML) with common concepts that can be shared among all other formats that want "hypermedia" embedded in them.

Great points. 

To clarify my earlier posts, it's not so much "one true media type" (which was Mike Kelly's title :) but instead a "standard." The standard should enable the development of open source libraries for Javascript, PHP, Ruby, Python, .NET, Java, etc. for working with REST level 3 web services and allow companies like Apigee to update their API consoles to simplify testing and interaction.  That might be one true media type, or if might be a common base like you suggest, with several well-known extensions.  

I do think radical simplicity will be important for this. The more people will have to learn to "do it right", the fewer likely people will adopt it so the common base may be what's needed by definition.

-Mike

[Sam Ramji]

This seems like a great idea to me.  As someone who bears the scars of being on both the customer and vendor side during standards developments/wars, I am no longer a big believer in IETF/OASIS/W3C as the place to solve things.

Open Web Foundation, started by Chris Messina and David Recordon and others to be an "Apache for Standards" has developed good licenses that can be used by practitioners/ad-hoc standards developers.  This is (as you all probably know) how OAuth 1.0 came to be - without which we would not have OAuth 2.0.

Regardless of other standards committees looking at the same thing, it is still a great idea to have another well-developed point of view that can inform the eventual "official" standard.  For an example of how this has worked well (with tension between different points of view) look at EcmaScript aka JavaScript.

Cheers,

Sam

[Mike Schinkel]

Hi Sam,

On May 25, 2012, at 7:35 PM, Sam Ramji wrote:

This seems like a great idea to me.  As someone who bears the scars of being on both the customer and vendor side during standards developments/wars, I am no longer a big believer in IETF/OASIS/W3C as the place to solve things.

I think you are in a great position to drive this kind of thing. You are a vendor with a business reason drive adoption but not a vendor with a proprietary axe to grind (as far as I know.) And you've got the industry clout to gain the respect and attention of key stakeholders.  Maybe RESTFest would be a good place for a kickoff meeting?

What do you think?

-Mike

[Mike Kelly]

what are the practical differences of taking a specification through
OWF instead of IETF, etc?

Cheers,
M

[Scotty Logan]

On Fri, May 25, 2012 at 5:15 PM, Mike Kelly <mikeke...@gmail.com> wrote:
> what are the practical differences of taking a specification through
> OWF instead of IETF, etc?

It's not necessarily an either-or situation. Chris Messina, back in 2008:

"[…] the OWF is not a standards body, nor has intentions to become
one. We span the gap between community-driven approaches without
formal IP practices/policies and ones that do (W3C et al) if anything,
we're complementary and should help community projects generate
specifications with clean IP, lining them up for later industry-wide
standardization."

http://www.25hoursaday.com/weblog/2008/07/26/SomeThoughtsOnTheOpenWebFoundation.aspx#d4583cc2-4d92-470f-a875-ed60ff49d6fe

Scotty

[Mark Nottingham]

Just tripped across this thread (hi!), wanted to clarify a few things.

Someone (not sure, it was copied from another thread) said:

My reservations are not about the spec, they are about the fact that not everyone on this list agrees that HAL is the one way to do hypermedia in REST.  [...] Mark Nottingham thinks is should be home-json.

To be clear: I'm not positioning json-home as the One True (or even "a") solution to hypermedia in REST; that's way too broad of a problem to tackle, and personally I think you're getting to diminishing returns by trying. At most, some conventions for linking are what's required.

json-home is trying to solve the problem of how to introduce a client to the resources in an API *using* hyperlinking. 

Regarding HAL, BTW, I'm somewhat ambivalent; I have reservations about using a media type to define a linking convention, as well as some of the details.

 

On Saturday, May 26, 2012 9:35:39 AM UTC+10, Sam Ramji wrote:

This seems like a great idea to me.  As someone who bears the scars of being on both the customer and vendor side during standards developments/wars, I am no longer a big believer in IETF/OASIS/W3C as the place to solve things.

I agree that doing innovation in standards bodies is hard (and often inappropriate), but sometimes it does work. Of the three, I've found IETF to be the most functional, especially when you get a *good* and *broad* group of people at the table to hammer out the starting point first (it doesn't work if it's just a couple of people with a good idea). E.g., see the WebRTC work currently going forward (which started as a private-ish collaboration).

Choosing the scope and timing is the part that takes some judgement.

Cheers,

[Mike Schinkel]

On Jul 3, 2012, at 7:27 PM, Mark Nottingham wrote:

Someone (not sure, it was copied from another thread) said:

My reservations are not about the spec, they are about the fact that not everyone on this list agrees that HAL is the one way to do hypermedia in REST.  [...] Mark Nottingham thinks is should be home-json.

To be clear: I'm not positioning json-home as the One True (or even "a") solution to hypermedia in REST; that's way too broad of a problem to tackle, and personally I think you're getting to diminishing returns by trying. At most, some conventions for linking are what's required.

I believe that someone was me. 

And the point was not to argue for a "One True" solution (someone else titled the thread) but instead that the hypermedia constraint that purists argue for is a non-starter for most public web APIs because IMO it puts too much burden on the client developer.  Most (almost all?) public web APIs prescribe URL construction because IMO there isn't a standard enough method for hypermedia that few if any browsers/libraries/languages/open-source projects have implemented clients for interacting with hypermedia-based web services.  

Hypermedia puts the burden on the client developer to architect, build, and test to an acceptable level of robustness which 1.) significantly increases costs and time-to-market for the client developer and 2.) almost certainly retards API adoption.  So IMO because the benefits of hypermedia are not immediately obvious to many people it remains a still-bourne concept.

So my point was that those who so strenuously advocate for hypermedia should really corral their efforts to make consuming hypermedia web APIs as trivially easy as consuming web APIs that prescribe URL construction. The "One True" media type was just one such discussion that evolved from that idea.

And serendipitously, you IMO are one of the few people who has the credentials to drive an industry solution to this problem, if you were so inclined.

-Mike

P.S. I also think that whatever standard might emerge, it would need to be able to layered on top of an existing mostly-RESTful web API instead of requiring the API and all existing client software to be redeveloped.

[Mark Nottingham]

On 04/07/2012, at 9:53 AM, Mike Schinkel wrote:

> On Jul 3, 2012, at 7:27 PM, Mark Nottingham wrote:
>
>> Someone (not sure, it was copied from another thread) said:
>> My reservations are not about the spec, they are about the fact that not everyone on this list agrees that HAL is the one way to do hypermedia in REST. [...] Mark Nottingham thinks is should be home-json.
>>
>> To be clear: I'm not positioning json-home as the One True (or even "a") solution to hypermedia in REST; that's way too broad of a problem to tackle, and personally I think you're getting to diminishing returns by trying. At most, some conventions for linking are what's required.
>
> I believe that someone was me.
>
> And the point was not to argue for a "One True" solution (someone else titled the thread) but instead that the hypermedia constraint that purists argue for is a non-starter for most public web APIs because IMO it puts too much burden on the client developer. Most (almost all?) public web APIs prescribe URL construction because IMO there isn't a standard enough method for hypermedia that few if any browsers/libraries/languages/open-source projects have implemented clients for interacting with hypermedia-based web services.
>
> Hypermedia puts the burden on the client developer to architect, build, and test to an acceptable level of robustness which 1.) significantly increases costs and time-to-market for the client developer and 2.) almost certainly retards API adoption. So IMO because the benefits of hypermedia are not immediately obvious to many people it remains a still-bourne concept.
>
> So my point was that those who so strenuously advocate for hypermedia should really corral their efforts to make consuming hypermedia web APIs as trivially easy as consuming web APIs that prescribe URL construction. The "One True" media type was just one such discussion that evolved from that idea.

Don't disagree on any point. I'd also like to see less hand-waving and more software, more tangible benefit.

> And serendipitously, you IMO are one of the few people who has the credentials to drive an industry solution to this problem, if you were so inclined.

Thanks. I'm inclined to give it a good go; json-home is a start, next is some software to show how / why.

> -Mike
> P.S. I also think that whatever standard might emerge, it would need to be able to layered on top of an existing mostly-RESTful web API instead of requiring the API and all existing client software to be redeveloped.

Yep, that's one of my primary goals too. Big question is how much bad practice to accommodate.

Cheers,


--
Mark Nottingham http://www.mnot.net/

[Mike Schinkel]

On Jul 3, 2012, at 8:01 PM, Mark Nottingham wrote:

And the point was not to argue for a "One True" solution (someone else titled the thread) but instead that the hypermedia constraint that purists argue for is a non-starter for most public web APIs because IMO it puts too much burden on the client developer.  Most (almost all?) public web APIs prescribe URL construction because IMO there isn't a standard enough method for hypermedia that few if any browsers/libraries/languages/open-source projects have implemented clients for interacting with hypermedia-based web services.  

Hypermedia puts the burden on the client developer to architect, build, and test to an acceptable level of robustness which 1.) significantly increases costs and time-to-market for the client developer and 2.) almost certainly retards API adoption.  So IMO because the benefits of hypermedia are not immediately obvious to many people it remains a still-bourne concept.

So my point was that those who so strenuously advocate for hypermedia should really corral their efforts to make consuming hypermedia web APIs as trivially easy as consuming web APIs that prescribe URL construction. The "One True" media type was just one such discussion that evolved from that idea.

Don't disagree on any point. 

I made a lot of assertions above, like that hypermedia increases costs and time-to-market, that hypermedia retards API adoption, that hypermedia places too much burden on the developer, that most public APIs prescribe URL construction, that there is no standard for hypermedia, that browsers/libraries/languages/open-source projects have implement a standard for hypermedia, or that URL construction is prescribed for more reasons than there being few browsers/libraries/languages/open-source projects?  Or something else I didn't mention?

So may I ask, did you disagree with all, including things which I think are fact (i.e. that few web APIs prescribe hypermedia?)  For those you disagree with, might I ask for to please explain why? I respect your opinion and really want to know.

I'd also like to see less hand-waving and more software, more tangible benefit. 

Agreed.  But hopefully you'd agree that few people are in a position to actually affect a standard?  I know that I am not; I'm self-employed and not sponsored by an industry heavy weight and have no prior standards experience to speak of.

Thanks. I'm inclined to give it a good go; json-home is a start, next is some software to show how / why.

Cool.

P.S. I also think that whatever standard might emerge, it would need to be able to layered on top of an existing mostly-RESTful web API instead of requiring the API and all existing client software to be redeveloped.

Yep, that's one of my primary goals too. Big question is how much bad practice to accommodate.

My opinion, which is only my opinion, is that if an API is mostly RESTful and JSON-based then it would be helpful if only a small, backward compatible addition would be required to enable hypermedia such as one top-level object property, or much better IMO, a link that returns a response defines hypermedia for the API using keys and values where one of the URIs would be specified as URI templates. That would be the lightest weight possible.  The API docs could specify the hypermedia reference resource so that the existing APIs could optional not have to reference it. Again, just my opinion.

-Mike

P.S. Have a Happy July 4th, assuming you are currently in the US to celebrate independence day.

[Mark Nottingham]

On 04/07/2012, at 11:10 AM, Mike Schinkel wrote:

> On Jul 3, 2012, at 8:01 PM, Mark Nottingham wrote:
>>> And the point was not to argue for a "One True" solution (someone else titled the thread) but instead that the hypermedia constraint that purists argue for is a non-starter for most public web APIs because IMO it puts too much burden on the client developer. Most (almost all?) public web APIs prescribe URL construction because IMO there isn't a standard enough method for hypermedia that few if any browsers/libraries/languages/open-source projects have implemented clients for interacting with hypermedia-based web services.
>>>
>>> Hypermedia puts the burden on the client developer to architect, build, and test to an acceptable level of robustness which 1.) significantly increases costs and time-to-market for the client developer and 2.) almost certainly retards API adoption. So IMO because the benefits of hypermedia are not immediately obvious to many people it remains a still-bourne concept.
>>>
>>> So my point was that those who so strenuously advocate for hypermedia should really corral their efforts to make consuming hypermedia web APIs as trivially easy as consuming web APIs that prescribe URL construction. The "One True" media type was just one such discussion that evolved from that idea.
>>
>> Don't disagree on any point.
>
> I made a lot of assertions above, like that hypermedia increases costs and time-to-market, that hypermedia retards API adoption, that hypermedia places too much burden on the developer, that most public APIs prescribe URL construction, that there is no standard for hypermedia, that browsers/libraries/languages/open-source projects have implement a standard for hypermedia, or that URL construction is prescribed for more reasons than there being few browsers/libraries/languages/open-source projects? Or something else I didn't mention?
>
> So may I ask, did you disagree with all, including things which I think are fact (i.e. that few web APIs prescribe hypermedia?) For those you disagree with, might I ask for to please explain why? I respect your opinion and really want to know.

I think that the costs are real, and that the burden needs to be justified / mitigated. I think it *presently* puts too much burden on the client; hopefully that can be addressed.

The low rate of adoption is due to people only recently understanding it, and only partially at that, and also because simple APIs (such as Twitter's, etc.) don't see as much benefit. See: <http://www.mnot.net/blog/2012/06/25/http_api_complexity_model>

That said, I see the number of APIs using linking growing; I've come across a fair number that don't define static URIs, but instead have the client fetch something with links first.

I'll be blogging more about this (hopefully) soon, in the context of json-home.

>> I'd also like to see less hand-waving and more software, more tangible benefit.
>
> Agreed. But hopefully you'd agree that few people are in a position to actually affect a standard? I know that I am not; I'm self-employed and not sponsored by an industry heavy weight and have no prior standards experience to speak of.
>
>> Thanks. I'm inclined to give it a good go; json-home is a start, next is some software to show how / why.
>
> Cool.
>
>>> P.S. I also think that whatever standard might emerge, it would need to be able to layered on top of an existing mostly-RESTful web API instead of requiring the API and all existing client software to be redeveloped.
>>
>> Yep, that's one of my primary goals too. Big question is how much bad practice to accommodate.
>
> My opinion, which is only my opinion, is that if an API is mostly RESTful and JSON-based then it would be helpful if only a small, backward compatible addition would be required to enable hypermedia such as one top-level object property, or much better IMO, a link that returns a response defines hypermedia for the API using keys and values where one of the URIs would be specified as URI templates. That would be the lightest weight possible. The API docs could specify the hypermedia reference resource so that the existing APIs could optional not have to reference it. Again, just my opinion.
>
> -Mike
> P.S. Have a Happy July 4th, assuming you are currently in the US to celebrate independence day.

Nope, just another day in Australia :)

[Mike Schinkel]

On Jul 3, 2012, at 9:26 PM, Mark Nottingham wrote:

Don't disagree on any point.

I made a lot of assertions above, like that hypermedia increases costs and time-to-market, that hypermedia retards API adoption, that hypermedia places too much burden on the developer, that most public APIs prescribe URL construction, that there is no standard for hypermedia, that browsers/libraries/languages/open-source projects have implement a standard for hypermedia, or that URL construction is prescribed for more reasons than there being few browsers/libraries/languages/open-source projects?  Or something else I didn't mention?

So may I ask, did you disagree with all, including things which I think are fact (i.e. that few web APIs prescribe hypermedia?)  For those you disagree with, might I ask for to please explain why? I respect your opinion and really want to know.

I think that the costs are real, and that the burden needs to be justified / mitigated. I think it *presently* puts too much burden on the client; hopefully that can be addressed.

The low rate of adoption is due to people only recently understanding it, and only partially at that, and also because simple APIs (such as Twitter's, etc.) don't see as much benefit. See: <http://www.mnot.net/blog/2012/06/25/http_api_complexity_model>

That said, I see the number of APIs using linking growing; I've come across a fair number that don't define static URIs, but instead have the client fetch something with links first.

I'll be blogging more about this (hopefully) soon, in the context of json-home.

Damn you write fast!  Thanks for elaborating.

Nope, just another day in Australia :)

If it's all the same, wish I were there. :)

-Mike

[Mike Kelly]

On Wed, Jul 4, 2012 at 12:27 AM, Mark Nottingham <mn...@mnot.net> wrote:
> Just tripped across this thread (hi!), wanted to clarify a few things.
>
> Someone (not sure, it was copied from another thread) said:
>>
>> My reservations are not about the spec, they are about the fact that not
>> everyone on this list agrees that HAL is the one way to do hypermedia in
>> REST. [...] Mark Nottingham thinks is should be home-json.
>
>
> To be clear: I'm not positioning json-home as the One True (or even "a")
> solution to hypermedia in REST; that's way too broad of a problem to tackle,
> and personally I think you're getting to diminishing returns by trying. At
> most, some conventions for linking are what's required.
>
> json-home is trying to solve the problem of how to introduce a client to the
> resources in an API *using* hyperlinking.

What benefit is there in drawing a distinction between links within an
application (HAL) and links at the entry points (home-json)?

Afaict there are no benefits in doing so and it just increases the
risk that the entry point will be seen as a WADL-for-JSON or some
other design-time boilerplate (i.e. documentation) that people refer
to but don't actually drive their clients through. In being 'entry
point specific' it potentially sends out the wrong message and defeats
its purpose before its started.

> Regarding HAL, BTW, I'm somewhat ambivalent; I have reservations about using
> a media type to define a linking convention, as well as some of the details.

Please could you be more specific? There's 100 people on the
hal-discuss google group that would likely want to hear your
input/suggestions - please get involved.

Cheers,
M

[Mike Kelly]

On Wed, Jul 4, 2012 at 1:01 AM, Mark Nottingham <mn...@mnot.net> wrote:
> On 04/07/2012, at 9:53 AM, Mike Schinkel wrote:
>
>> On Jul 3, 2012, at 7:27 PM, Mark Nottingham wrote:
>>
>>> Someone (not sure, it was copied from another thread) said:
>>> My reservations are not about the spec, they are about the fact that not everyone on this list agrees that HAL is the one way to do hypermedia in REST. [...] Mark Nottingham thinks is should be home-json.
>>>
>>> To be clear: I'm not positioning json-home as the One True (or even "a") solution to hypermedia in REST; that's way too broad of a problem to tackle, and personally I think you're getting to diminishing returns by trying. At most, some conventions for linking are what's required.
>>
>> I believe that someone was me.
>>
>> And the point was not to argue for a "One True" solution (someone else titled the thread) but instead that the hypermedia constraint that purists argue for is a non-starter for most public web APIs because IMO it puts too much burden on the client developer. Most (almost all?) public web APIs prescribe URL construction because IMO there isn't a standard enough method for hypermedia that few if any browsers/libraries/languages/open-source projects have implemented clients for interacting with hypermedia-based web services.
>>
>> Hypermedia puts the burden on the client developer to architect, build, and test to an acceptable level of robustness which 1.) significantly increases costs and time-to-market for the client developer and 2.) almost certainly retards API adoption. So IMO because the benefits of hypermedia are not immediately obvious to many people it remains a still-bourne concept.
>>
>> So my point was that those who so strenuously advocate for hypermedia should really corral their efforts to make consuming hypermedia web APIs as trivially easy as consuming web APIs that prescribe URL construction. The "One True" media type was just one such discussion that evolved from that idea.
>
> Don't disagree on any point. I'd also like to see less hand-waving and more software, more tangible benefit.

http://stateless.co/hal_specification.html#libraries_for_working_with_hal

There's also a browser for 'following your nose' through a HAL
application, a NYC-based company called dtime forked it and use it as
part of their developer documentation. You can also point it at any
OAuth'd HAL app:

http://explorer.dtime.com/

>> And serendipitously, you IMO are one of the few people who has the credentials to drive an industry solution to this problem, if you were so inclined.
>
> Thanks. I'm inclined to give it a good go; json-home is a start, next is some software to show how / why.

In light of you wanting to see less hand-waving and more software, I
think HAL is the far better option at this point. There are very few
features in home-json that weren't already in HAL, the ones that are
missing you are free to propose to the community where we can look to
incorporate them if it is felt that they are necessary additions.

Cheers,
M