Initial Abstraction of Hypermedia Elements

[fosrias]

I can put some initial content together on this as our team has worked on it quite a bit, if you all are good with that as a starting point.

Further, I think taking a look at: verbose.readthedocs.org/en/latest/specification.html for some ideas about abstract components of hypermedia messages.

In any case, thoughts?

[zdne]

:+1:

Also https://github.com/smizell/halpert-representer is something work looking at while thinking about Representor & co

[smizell]

The goal of Verbose was to be the basis for a representer model, and to also provide a way to capture all of the hypermedia elements in one message to be sent over the wire. The latter means that a Ruby representer object can serialize and send the data as JSON, and a Javascript representer can parse that and have the exact same representation. I don't think this is possible with any other hypermedia format at this point.

With that said, Verbose will mold and conform to this representer model that we all agree upon here since that's what it's purpose was. So please use whatever is there that is applicable, or make suggestions in ways that I can make it better for the betterment of everyone else on this project.

Just as a side note, I've done a few changes to Verbose recently, one of which was a big one–combining all of the different types of links, actions, and queries I had into one transition type. This definitely makes Verbose less.... verbose. It also makes it easier on the clients to find links. This all came from a conversation I had with Mark a while back where he asked me why I had split them up. It has been nagging me ever since :)

Halpert will be changing accordingly, but I'm going to wait on that until we work out more things here.

[glennblock]

@smizell +1 on formalizing transitions.

Are representers media-type specific or agnostic? Is the SematnicCollection where I attach media-type specfics?

For example, CJ has diff types of templates, Read, Write and Queries. How do I identify that this maps to a Read template in CJ?

[smizell]

I started a discussion on the Cj list here:

https://groups.google.com/forum/#!topic/collectionjson/6kqxtPWAjcc

On Fri, Aug 8, 2014 at 11:20 AM, Glenn Block notifications@github.com wrote:

@smizell https://github.com/smizell +1 on formalizing transitions.

Are representers media-type specific or agnostic? Is the SematnicCollection where I attach media-type specfics?

For example, CJ has diff types of templates, Read, Write and Queries. How do I identify that this maps to a Read template in CJ?

— Reply to this email directly or view it on GitHub https://github.com/the-hypermedia-project/charter/issues/4#issuecomment-51624120 .

[smizell]

I have a very rough draft of the document on hypermedia elements. After spending some time outlining it out, I decided to just put down some quick points on each element so I could get it online and we could start discussing. I'll continue working on expanding it as we work through it together.

https://github.com/smizell/charter/blob/master/hypermedia-elements.md

This is all up for discussion and change. Please pick this apart with reckless abandon :)

Some points I wanted to highlight about this.

Transition Categories

Even though we are using a basic transition here, I have broken it down into a few categories. This may be helpful in thinking through how media types represent transitions differently.

Queries

I have included a transition category for queries as I believe it is handled a little differently than a URI template (though you can accomplish the same things). Some media types support the idea of a query and keep it separate from normal link transitions. As I mentioned, even though we are not separating these in the Hypermedia Resource, it may be helpful to think of these concepts separately.

Embedded Resource

I have included embedded resource under the link category, which is an idea I've been thinking through recently. Reason being, as you look at all the different general hypermedia formats, there is a spectrum of ways to embed extra information about the link. It may be to include meta data, it may be to include what HTTP methods are available on a link, or it may be to include resource attributes and transitions.

While this is a different way to think about an embedded resource, I think it may be helpful to think of an embedded resource as a fully expanded link. It also may be helpful to consider an embedded resources as transitions. This is definitely open for discussion.

Anonymous Links and Actions

I have added an aspect to embedded resources that I referred to as anonymous links and actions (there may be a better name!). This is for situations where media types provide only HTTP methods available for a linked resource. The only difference, then, is that these links and actions do not have a relation type name.

Instead of supporting the idea of available methods, it may be helpful to think of these as anonymous actions. The action hypermedia clients can then make this information available however it sees fit, but it should be at least made available (down the road of course).