hypermedia json forms

[Terren Suydam]

Hi all,

Wondering if there's any decent public APIs out there that demonstrate hypermedia responses (in JSON) that construct forms for updating data. Anyone know of any?

Thanks,

Terren

[mca]

Terren:

Not sure if this is what you are asking, but you can checkout my Collection+JSON hypermedia design[1]. I also posted a sample generic JS client (in github[2]) that generates HTML.FORM elements "on the fly" based on the JSON representation returned to the client.

Even if this is not exactly what you need, it might give you some ideas on how to tackle your own problem.

Feel free to write me directly if you have questions specific to the media type.

[1]  http://amundsen.com/media-types/collection/ 

[2]  https://github.com/mamund/collection-json 

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

[Terren Suydam]

I'm trying to decide whether to do a hypermedia response or force
client developers to do url construction. I love the idea of providing
links in the response, and for GETs nothing could be simpler. But for
updates (of whatever kind) the situation is more muddled. Even for
simple examples like below it seems to me the API developers that
might use my API would have an easier time with URL construction -
unless there were some standard out there with library support for
client devs.

Off the top of my head I'm looking for public examples that *might*
look something like this:

GET http://.../resources/123
...
update: {
verb: PUT
params: [
{name: field1, type: string, max-length: 64, mandatory: true},
{name: field2, type: integer, min-value: 0, max-value: 100},
// and so on with potentially many kinds of parameter types and constraints
]

[Mike Kelly]

Hey Terren,

I'm currently working on a new media type halo+json which I think provides some of the form capabilities you are looking for:

https://gist.github.com/893552

Cheers,

Mike

--
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

[Terren Suydam]

That's helpful... are there real-world examples of APIs using either
collections or halo?

Thanks,
Terren

[Mike Kelly]

Not right now, but halo+json is a new media type I'm designing now that's based on hal+json

hal+json is already in use, there's a number of libraries that exist for it:

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

and here's one example of how it's being used in the wild:

https://gist.github.com/2289546

Cheers,

M

[mca]

Terren:

feel free to drop by the discussion group:

https://groups.google.com/forum/?fromgroups#!forum/collectionjson 

there are a few ppl there working on projects based on the collection media type.

again, ping me offline (mam...@yahoo.com) if' you'd like to talk specifics off-list

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

[Terren Suydam]

Thanks guys. I don't think I'm going to go in that direction.

I do like hal though for the _links and _embedded patterns.

Mike, are there any issues with returning application.hal+json with
ajax responses for older web browsers? Or do the browsers' ajax
objects ignore the media type?

Terren

[Mike Kelly]

Hey Terren,

afaik, there are no issues with parsing responses with alternative content-type headers as JSON. hal+json is valid JSON so it's not a problem.

Cheers,

M

[Mike Schinkel]

Hi Terren,

On this thread thus far I'm going to be the one guy saying the Emperor has no clothes.

Yes, REST has the hypermedia constraint or as some on this list like to say "Level 3 REST" but in practice it adds a potentially significant burden to would-be clients when compared to URL construction. 

IF there were a standard media type for RESTful interactions that was simple to implement and the majority of people where happy to use and IF there were available open-source libraries for all common languages and platforms for interacting with this hypothetically widely adopted standard for fully RESTful APIs THEN it would be hard to argue against "Level 3 REST."  But that isn't the case.

Time is money and there are no standards nor standard software for REST Level 3. Given that I would choose URL construction over hypermedia for a public API client if I were given the choice. And if I cared about API adoption, I wouldn't even consider using hypermedia because doing so would limit the number of people who would successfully end up using it.

JMTCW.

-Mike

P.S. For those who may want to take issue with me for this, please put your efforts into establishing ONE single standard media type and a bunch of open source client libraries rather than debate me because until that happens there are too many negatives for hypermedia on a public API. And you know I'm right because if I were wrong there would be more (are there any?) public APIs that are REST Level 3.

[Jack Repenning]

On May 24, 2012, at 12:39 PM, Mike Schinkel wrote:

Yes, REST has the hypermedia constraint or as some on this list like to say "Level 3 REST" but in practice it adds a potentially significant burden to would-be clients when compared to URL construction. 

So, as you "bah, humbug" your way through the topic, how do you feel about URL templates for URL construction?

Jack Repenning

I grow old ... I grow old... 

dBase-II and WordStar are no longer sold. 

      - The Love Song of J. Random Hacker

      - http://www.duntemann.com/lovesong.htm

[Mike Schinkel]

So, as you "bah, humbug" your way through the topic,

My "bah humbuging" on the topic is me saying: 

"If you feel it's important, don't preach, take effort to make it practical. 

Just please stop preaching that which is impractical."

how do you feel about URL templates for URL construction?

URL templates are just a streamlined form of hypermedia, IMO.

-Mike 

[mca]

On Thu, May 24, 2012 at 3:50 PM, Mike Schinkel <mi...@newclarity.net> wrote:

So, as you "bah, humbug" your way through the topic,

My "bah humbuging" on the topic is me saying: 

"If you feel it's important, don't preach, take effort to make it practical. 

Just please stop preaching that which is impractical."

*****************

and to whom are you addressing this remark?

**************** 

[Mike Schinkel]

My "bah humbuging" on the topic is me saying: 

"If you feel it's important, don't preach, take effort to make it practical. 

Just please stop preaching that which is impractical."

and to whom are you addressing this remark?

No one person in specific but a general plea to those who haven't or won't publicly acknowledge that adding hypermedia places significant burdens on prospective client developers.

Actually, what I'd really like to see is a working group with full industry support formed to resolve the issue, i.e. to develop a lightweight standard media type for hypermedia REST that the majority of stakeholders could agree on so that open-source libraries could emerge. But what we have instead is for years people saying "Oh, it must be hypermedia" but there has been no collective action to make it practical.

-Mike 

[Mike Kelly]

On Thu, May 24, 2012 at 8:39 PM, Mike Schinkel <mi...@newclarity.net> wrote:
>
> Hi Terren,
>
>
> On this thread thus far I'm going to be the one guy saying the Emperor has no clothes.
>
> Yes, REST has the hypermedia constraint or as some on this list like to say "Level 3 REST" but in practice it adds a potentially significant burden to would-be clients when compared to URL construction.
>
> IF there were a standard media type for RESTful interactions that was simple to implement and the majority of people where happy to use and IF there were available open-source libraries for all common languages and platforms for interacting with this hypothetically widely adopted standard for fully RESTful APIs THEN it would be hard to argue against "Level 3 REST."  But that isn't the case.
>
> Time is money and there are no standards nor standard software for REST Level 3. Given that I would choose URL construction over hypermedia for a public API client if I were given the choice. And if I cared about API adoption, I wouldn't even consider using hypermedia because doing so would limit the number of people who would successfully end up using it.
>
>
> JMTCW.
>
>
> -Mike
> P.S. For those who may want to take issue with me for this, please put your efforts into establishing ONE single standard media type and a bunch of open source client libraries rather than debate me because until that happens there are too many negatives for hypermedia on a public API. And you know I'm right because if I were wrong there would be more (are there any?) public APIs that are REST Level 3.

Hi Mike,

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.

Cheers,
M

[Mike Kelly]

On Thu, May 24, 2012 at 9:09 PM, Mike Schinkel <mi...@newclarity.net> wrote:
>> My "bah humbuging" on the topic is me saying:
>>
>> "If you feel it's important, don't preach, take effort to make it
>> practical.
>> Just please stop preaching that which is impractical."
>
>
> and to whom are you addressing this remark?
>
>
> No one person in specific but a general plea to those who haven't or won't
> publicly acknowledge that adding hypermedia places significant burdens on
> prospective client developers.

You can argue that point for form-based controls but not for basic links.

In practical terms, a basic link gives a client a string that they
would otherwise have to *construct themselves* according to some URL
construction logic - if anything that is less complicated from the
client's point of view.

> Actually, what I'd really like to see is a working group with full industry
> support formed to resolve the issue, i.e. to develop a lightweight standard
> media type for hypermedia REST that the majority of stakeholders could agree
> on so that open-source libraries could emerge. But what we have instead is
> for years people saying "Oh, it must be hypermedia" but there has been no
> collective action to make it practical.

Absolutely, and this is exactly what hal was created for. It doesn't
have any form controls; form controls are being added to a separate
media type (halo+json) extending hal.

Cheers,
M

[Mike Schinkel]

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.

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.

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.

-Mike

[1] http://stateless.co/hal_specification.html

[Mike Schinkel]

On May 24, 2012, at 4:26 PM, Mike Kelly wrote:

In practical terms, a basic link gives a client a string that they
would otherwise have to *construct themselves* according to some URL
construction logic - if anything that is less complicated from the
client's point of view.

With URL construction an occupational programmer can make one HTTP call to access an API; this is basically declarative in nature.

With hypermedia an occupational programmer has to make an HTTP call, apply logic to the response and then make a 2nd (or subsequent) HTTP call(s). This is procedural and the level of development skills required goes up.

Lots of people accessing public APIs are graphic designers building websites who only write Javascript or PHP because they have no other choice. Hypermedia APIs make it effectively impossible for many of these people to use them in the websites they build. Good programmers often discount how hard it is for occasional programmers to do things that they see to be trivial. At least that's my experience in the WordPress community which is the platform that populates over 14% of the web.  

So if it's a public API then hypermedia raises the bar for entry and reduces adoption. In my experience.

Absolutely, and this is exactly what hal was created for. It doesn't
have any form controls; form controls are being added to a separate
media type (halo+json) extending hal.

Okay, so where's the working group?  Why is Mark Nottingham publishing a competing spec[1] with Rackspace?

I'm not being confrontational, I'm just asking questions that needs to be answered to move things forward.

-Mike

[1] http://tools.ietf.org/html/draft-nottingham-json-home-00

[Daniel Roop]

Terran,

Bet you didn't think you were stepping into this, when you sent that email ;-).  I have not seen any public examples that use JSON and hypermedia.  There are plenty that use XML and hypermedia, netflix, atlassian, (any atom document), rss, etsy, restbucks.

And as has been pointed out there are numerous people proposing solutions in the json space:

http://amundsen.com/media-types/collection/format/

http://stateless.co/hal_specification.html

http://tools.ietf.org/html/draft-nottingham-json-home-00

http://www.wrml.org/

And I am sure there are a handful of companies who have an internal flavor they are developing (like at my company).

I of course have my own opinion of the various topics on this thread, but take that over to the new thread that opened on that topic.  The one thing I will say here is, that I do agree that an ideal end state would be to have a "webkit for rest apis" would be ideal, so that we can add new features like "forms" and "embeddable links" into the standard and the client (user-agent) will abstract that from the user (your application).  This will allow us to conform to the "rest principals" while still allowing the casual programmer to take advantage of the approach with minimal effort/bootstrapping.  I do however think very simple hypermedia controls are useful even without that,  the most basic being a "link" concept.  The only difference between that and URL Construction is that the client doesn't have to lookup an id property and build a link, they just use the link.  

Daniel Roop

[Jørn Wildt]

> "If you feel it's important, don't preach, take effort to make it practical. Just please stop preaching that which is impractical."

Sure. See https://github.com/JornWildt/Ramone - that's a client side
library for consuming hyper media driven services :-)

But, yes, its in C# and unfortunately that won't help the graphical
non-programmer designers you mention. But its a step in the right
direction.

/Jørn

[Mike Schinkel]

On May 25, 2012, at 12:43 AM, Jørn Wildt wrote:

"If you feel it's important, don't preach, take effort to make it practical. Just please stop preaching that which is impractical."

Sure. See https://github.com/JornWildt/Ramone - that's a client side
library for consuming hyper media driven services :-)

But, yes, its in C# and unfortunately that won't help the graphical
non-programmer designers you mention. But its a step in the right
direction.

Yes, but yet another approach actually makes it worse, not better.  :)

We need a standard solution that the industry generally agrees on, not a cornucopia of approaches:

https://github.com/JornWildt/Ramone

http://amundsen.com/media-types/collection/format/

http://stateless.co/hal_specification.html

http://tools.ietf.org/html/draft-nottingham-json-home-00

http://www.wrml.org/

And several more, I'm sure...

-Mike