My hypermedia talk at Oredev

[Glenn Block]

Hi folks

I recently delivered a talk on building hypermedia systems with ASP.NET Web API. It is online here: http://vimeo.com/53261707. The talk is in two main parts with the first focusing on the what and why of Hypermedia and the second on approaches.

Feedback welcome.

Glenn

[landlessness]

great stuff, Glenn.

very helpful for a hypermedia luddite like me to see lotsa code.

also, somehow I had missed the HTML as API media type discussion back in July. thanks for calling that out.

-b

[Glenn Block]

Sure thing Brian. 

The one thing that didn't work in the talk was showing consumption of the XHTML API from a non-browser client. For some reason I got a weird error so I skipped over it. However if you look in the RestBugs project, there is a console client which "should" work.

As for the hypermedia discussion, that was more of a chronicle than a discussion, but good stuff there.

I am still of the mind that I see the usefullness of XHTML but it's not the One-True-MediaType-That-Rules-Them-All for me :-)

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
 
 

[Kevin Swiber]

Watching now!

Glenn, I see you have a Node version of RestBugs (https://github.com/glennblock/RestBugs), which is cool.  Do you know if the .NET version will run on Mono for the non-Windows OS folks?

For list posterity:  To add some context around the "HTML for Hypermedia APIs" discussion, Jon Moore has a good post here:  http://codeartisan.blogspot.com/2012/07/using-html-as-media-type-for-your-api.html.  It links back to some relevant API Craft conversations.  There was also a lot of Twitter chatter going around at that time.  I'll spare you that conversation.  :)

[Glenn Block]

Hey Kevin

RestBugs was written by Howard Dierking, this is just my fork which adds in using a JSON template.

As to Mono, I believe Web API does work on Mono at least on top of ASP.NET. Not sure for self-host which the example uses, but I'll check.

[Roberto Modica]

Hi Glenn,

Great talk, its nice to have a higher level representation of this stuff, with all the specs, dissertations etc. it sometimes gets a bit heave, this video has given me some inspiration of the node based Hypermedia API we are building at the start-up i am involved in.

Also nice to see some great stuff coming out of Microsoft, Web API looks great.

Collection+Json is the main Media type in the talk, and i have read about that in Mikes book , and even began to implement it(we created the formatter to deal with the general output) but it started to get a little verbose for us, especially when working with javascript and you losing the .notation to interact with the data for each object and having everything output as essentially a name value pair...

Rob

[mca]

Jumping in here...

the biggest challenge (some would say drawback) to using my Collection+JSON media type is that it was specifically designed to "break the back" of object-style serializers in code libraries<g>.

I find that facing the notion of switching communications between machines from object-oriented to state-oriented can be enlightening, even if it turns out that's not what you decide to do for your project.

I think HAL does a very good job of providing hypermedia affordances while still supporting object-style message passing.  Be sure to check that one out, too. It's also possible Siren would be a good fit, but I've not built much w/ that one yet.

Cheers.

mca

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

--

[Roberto Modica]

Hi Mike,

It wasn't a criticism, hope it didn't come across like that, from reading your book (which really is great by the way) with json not having the HFactors built in  and going for a general style like you have it is not going to fit every problem but will work for many, we get that, its clearly outlined in the chapter where you introduce it. 

We have implemented the formatter, so the promise was there and we took it, and we have a very basic implementation outputting collection+json and the data fits, and will continue to fit moving forwards, if we add things the API will evolve and version-ing in this instance shouldn't be an issue as everything is discoverable, and for that you have done a really great job.  Its just when we started implementing a simple client, we just seemed to lose the object style we are used too.  Some of this is down to understanding as well, because we are trying to shift the mindset from human API's to an API for everything, machine and all, and that is sometimes the difficult notion to wrap your head around, even if the concept is simple when you read it out loud.

We are new to this, and the number of "REST"ish apis that are around have probably clouded the judgement because they are all focused on the object being the resource (model to resource direct mapping) as they pan out their REST philosophy, when i guess the switch has to be from a point of view of the resources being agnostic and discoverable, which with collection+json they are and a truer representation or REST.

We are looking at Hal at the moment, comparing the two and see which will fit our problem that little bit better (we may stick with collection+json or use both :)) 

Great to have all the leaders in this field actively come and comment, really is a great boost for people to further their knowledge.

Rob

[mca]

Roberto:

totally understand where you are coming from here. no need to apologize, etc. your observations are spot on and this is a great forum for discussing the pros/cons of any design when implementing a real-life solution.

keep up the good work and continue to post here as there are lots of folks who are interested in the details (good and bad) arising from a real-life implementation.

cheers.

mca

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

[Glenn Block]

Sorry i am late to the convo.

Roberto, glad to help. 

Mike, I like the fact that collection+json leads away from pure object serialization toward more loose data. It works fine with web api, and in this case I constructed types to for the message structure.

[Glenn Block]

As to the whole debate of using messages vs objects, this same debate has been going on since the SOAP days, as in the early days SOAP was RPC, but it later evolved into a message / state based protocol, though most vendors never really go t on board with that model.

[Mike Kelly]

On 22 Nov 2012, at 18:11, Glenn Block <glenn...@gmail.com> wrote:

> Sorry i am late to the convo.
>
> Roberto, glad to help.
>
> Mike, I like the fact that collection+json leads away from pure object serialization toward more loose data. It works fine with web api, and in this case I constructed types to for the message structure.

Hi Glenn,

Can you clarify what you mean here I'm not sure I get it!

Cheers,
M

[Glenn Block]

Which part?

[Mike Kelly]

"collection+json leads away from pure object serialization toward more

loose data"0

--
Mike

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

[Glenn Block]

Meaning collection+json uses key-value for data transfer.

[Mike Kelly]

a JSON object is key-value anyway though.. right?

On Fri, Nov 23, 2012 at 4:22 PM, Glenn Block <glenn...@gmail.com> wrote:
> Meaning collection+json uses key-value for data transfer.
>

[Glenn Block]

Sure it is, but that is not the point.

On 11/23/12, Mike Kelly <mikeke...@gmail.com> wrote:

[Glenn Block]

Actually it us not simple key-value, it is a nested hierarchy of key-values.

On 11/23/12, Mike Kelly <mikeke...@gmail.com> wrote:

[Mike Kelly]

ok. if that's not the point - what is the point? :)

in other words: what's the connection between "preventing nested k/v
heirarchies in JSON" and "leading away from pure object serialization
toward more loose data"?

Cheers,
M

[Glenn Block]

I think the point is that Mike A is discouraging a style where you simply pass your application objects bi-directionally over the wire using a serializer. Instead it encourages extracting data elements / decoupling from the implementation. 

[Mike Kelly]

On Sat, Nov 24, 2012 at 11:47 AM, Glenn Block <glenn...@gmail.com> wrote:
> I think the point is that Mike A is discouraging a style where you simply
> pass your application objects bi-directionally over the wire using a
> serializer. Instead it encourages extracting data elements / decoupling from
> the implementation.
>

Afaict, decoupling is mainly encouraged here because the transfer of
information between client and server is driven through a given media
type (i.e. the uniform interface constraint). In this case you have
picked mamund's cj, but this principal applies equally to other media
types such as hal+json, siren, etc.

I think clunkiness or friction between a given media type and an
"implementation" might force some decoupling to be put in place (i.e.
resurrecting the V in your MVC frameworks for your APIs), but that
specific type of decoupling is behind the interface and internal to a
client or server - so it's not related to decoupling between client
and server. Also, one obvious consideration/trade-off here is that
more friction means a degraded user experience (where a user is a
developer), which may or may not be ok depending on how you feel about
encouraging adoption, learning curves, developer productivity, etc.

It doesn't take too much 'twiddly bits' in a media type to add enough
friction to render basic object serialization unsuitable. For example,
hal+json has maintained the full richness of the JSON object model,
and yet we have View/templating libraries for it across most major
programming languages[1]. Of course, I might be missing your point
here and that is not what you meant at all by 'decoupling from the
implementation'!

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

Cheers,
M

[Glenn Block]

Mike I appreciate the work you've done with HAL, but you are a little too dogmatic / religious in your defense of it. I don't think it's necessary every time hypermedia or media types are mentioned that one needs to affirm or deny, or defend their statements based on HAL's existence. It is a fine format, but there is life after HAL.

Get over it.

[Mike Kelly]

With all due respect I couldn't give a monkies about your meta-objections to the points I make.

Next time you don't have a direct response to make, it's more efficient for everyone if you just don't reply.

Cheers,

M

[Brian Topping]

It does seem like a thread that you could have stayed out of, Mike.  HAL got mentioned early on and Glenn didn't make any effort to dismiss it.  As a disinterested observer, that interjection seemed more than adequate for your visibility needs.  But it seems that half of the responses to the thread were vague insinuations on your part.  

How would you have felt if the tables were turned?  Maybe you would have reacted more strongly.  I admire his diplomacy in the situation.

This isn't a war.  The community will make a de-facto decision on which effort is more viable, and it's always a great thing when there are multiple options under active development.  Directly interested parties are better off focusing on the benefits of their own techniques, improving them as they see opportunity.  If other techniques are suboptimal, align your messaging to make it clear that your techniques solve a problem other techniques don't even realize they have.  Users will gravitate toward those positives much more loyally than they will to less positive messaging.

$0.02...

[Mike Schinkel]

My two cents worth is I was surprised by both Glenn and your reactions Brian. I didn't think Mike's contribution was over the line; I found value in what he said.  And I'm not pro or con HAL. IMO anyway.

-Mike

[Glenn Block]

With all due respect

I started the thread. I don't have a problem with anyone objecting to another's perspective. This is after all an open discussion and a place to learn from each other.

I commented on Mike's comment about collection+json and how a design goal was to lead people away from pure serializers. You then questioned me about my response, disagreeing, which evolved into grilling me mentioning how the same applies to HAL, Siren etc. I gave my reasoning, which you didn't appear to be content with and you kept questioning it. The discussion was a bit frustrating because the conversation was not about HAL, it was about collection+json.

My response about religiosity about HAL was an honest perception, though admittedly I probably could have presented it better.

I meant what I said about HAL in terms of it being a fine format. I have personally recommend it to many customers, and have both blogged about it and mentioned it in talks. 

Anyway, my intent here is to learn and to share and not to resort to name calling. 

[Mike Kelly]

Sorry everyone, I have to bite.
(tl;dr there are perfectly legitimate reasons for drawing on hal+json
as an example.)

I'm not sure what your problem is Glenn. I 'grilled' you about this:

"[mamund], I like the fact that collection+json leads away from pure

object serialization toward more loose data"

You've described something as a "fact", without actually explaining
how that is the case. I was not clear about your reasoning, so I asked
you a bunch of questions to try and figure out where you were coming
from. There is nothing wrong with that. Why you are being defensive
and describing that as a 'grilling'?

It turns our your reasoning was something like "collection+json is a
media type that encourages decoupling by crippling the expressiveness
of JSON (into k/v) for representing state and thus forcing
implementors to add a layer of translation between their
'implementations' and the representations they exchange". I'm sorry
but I do not agree with that analysis, and I like to think I know a
bit about this stuff (maybe not as much as you or mamund?), so I
offered you a different perspective, which was..

Firstly, decoupling between _client and server_ in your API should be
the primary goal. This can be achieved by establishing shared
understanding around media types and link relations, so naturally this
principal applies to c+j - it is worth clarifying that this is a
general principal that applies to any hypermedia type (hence my
providing a list of alternatives).

Secondly, I do not buy the idea that it is necessary to run away from
JSON's object model because you want better decoupled implementations.
By far the easiest way for me to make this point is to refer to a
_real world example I am familiar with_ where a media type has
libraries for decoupling the representation but has not crippled JSON
in the same way. This happens to be hal+json.

Glenn, hopefully that clarifies why my drawing on hal+json was not
religious or dogmatic, but a genuine attempt to share my thoughts and
hear a response from you (which you have yet to share.) You are
clearly unhappy discussing this subject with me for whatever reason. I
suggest we move on or at least take this off-list.

Cheers,
M

[Glenn Block]

Mike, first I apologize for my response as I went overboard. I should make it a habit not to respond to emails when I first wake up in the morning ;-). In this case it was 4 am getting ready to go the airport and I was being a bit impatient as I didn't have time for a long answer. As you noted, I did come off overly defensive and abrasive. Moving on....

I don't think we need to take it offline because others have expressed interest in the discussion. I will take it offline however if we get a request for that.

"crippling the expressiveness of JSON"

I don't think I said (nor do I belive) that it cripples the expressiveness of JSON as it uses JSON quite effectively to express various aspects like queries, links and data.

"forces implementors"

I think forces is a strong word, I'd use encourage. On the data side, I see that it does discourages simply dumping an object graph across the wire and encourages a more explicit data transfer through it's use of data/templates. This does (imo) lead a developer to think more about exactly what they want to send. It also does (IMO) provide a layer of decoupling that again encourages a separation between how the backend data is stored vs represented.

This is not very different than the way the browser operates i.e. with standard HTML forms. It's just a different way to solve the problem with pros/cons, I am not saying it is the one way, or the right way. I am saying it is "A" way and one that I like. That doesn't make other ways wrong at all.

"Secondly, I do not buy the idea that it is necessary to run away from

JSON's object model "

I don't see collection+json as running away. It aligns very well with JSON's object model, it just doesn't align well with simply passing your applications objects across the wire.

"Glenn, hopefully that clarifies why my drawing on hal+json was not

religious or dogmatic,"

Thanks Mike. There was a point i was trying to make there, but it somehow got lost in my manner of expressing it. Regardless it was out of line.