Python Hypermedia Resource

[smizell]

I have just uploaded a very rough draft Python version of the Hypermedia Resource [1]. I wanted to give some highlights and discussion of my method and put down some things I came across that I thought were interesting. This is somewhat of a sidebar of our current discussion in #6.

Edit: While there is some implementation in here, I am meaning most of this for discussion towards this idea of a canonical interface. Most of the conceptual pieces can be found in the Hypermedia Elements doc.

Hypermedia DOM

In a discussion on one of the API lists, @mamund mentioned this idea of a DOM for hypermedia messages. This idea stuck in the back of my head ever since and actually started to surface as I was working on this implementation. Let me try to explain my thoughts there (I hope they line up with what Mike was thinking).

As I was organizing code around my idea of the Collections and Items, I noticed that I was in a sense building a general interface model to JSON arrays. A Collection is in a sense an array in JSON or even a tag with children in XML. The items can be of any sort, though mostly I was using the Item in the Collection as a JSON object (though you could create different types of Item objects that are specific for JSON/XML primitives). Once you have these Collections/Items, you are in a sense extending these types when you create a Collection/Item.

Each Collection/Item object would have the functionality to convert back to the primitive types. For instance, an Array Collection would have a function that would convert itself to an array and while calling a function on its children to convert them to primitive types. I put a non-working example of this in my code.

As a bonus, when the conversion is complete, you essentially have a Verbose object, which was the point of Verbose.

I am merely mentioning this because I do believe it is a different kind of implementation of this canonical hypermedia interface, as instead of having a single Builder class that knows how to build all of the different elements, you have Collection classes for each element that knows how to build its specific children. I'm also not saying this is the way it must be implemented, just showing a different idea.

Hypermedia Aspects

I also included the idea of hypermedia aspects per slides by @mamund. This came in handy, and I could see it coming in handy for other things as well. For instance, a normal link is immutable, so its attributes do not provide the same affordances that a mutable transition does. Since I can know if something is immutable, I can swap out the attributes.

Transition Categories

If you looked at my code and freaked out, I apologize! I know we were going with the idea of transition, but my code has links, queries, actions, and transitions. Rest assured, these items are merely objects that extend the transition object and provide organization. So underneath a link object is a transition object. I put this in there for a couple of reasons. First, to show some of the benefits of using collections/items, since you can essentially extend collections to new types. Second, to show that if we want, we can support the idea of transitions AND links/actions/queries, which may aid in adoption.

In my library, when you create a link, it actually gets added to the transition collection. That means the transition collection has all of the transition types, even the special type that is a combination of link, query, and action.

Embedded Resource as Transition

I've mentioned this with a few of you all and have been going back and forth, but in my example I am considering embedded resources to be a type of transition. This is because I believe there is a spectrum between a normal link that has only a rel and href and an embedded resource that has everything. In other words, as you add more data to a link, it approaches becoming an embedded resource.

I am still up in the air here, but it seems helpful for the hypermedia client to follow a fully embedded resource without doing a request. To the user, they shouldn't care if it's embedded or not, but to the client, it's helpful to know that it is a full resource.

Most Things are Hypermedia Resource

In my example, every transition except for the actions are essentially a Hypermedia Resource. This is allows for embedding some data in links, queries, and transitions. For instance, HAL provides the profile and deprecation properties which are essentially links for that resource. Considering a link to have all of the functionality of a Hypermedia Resource allows access to a meta object.

Interface to the Hypermedia Elements

In this library, I'm essentially coding to the hypermedia elements [2]. I have not gotten to curies or templated links and actions.

Templated Links and Actions

As I've worked through this, I believe templated items should be treated differently than normal links and actions (as I mention in the Hypermedia Element doc). I think a templated link should first be processed before being usable, and once processed, it should return a normal link transition, which should in turn be added to the transition collection.

Final Thoughts

It's time for bed. Please ask away! I'm writing this mainly as a brain dump of what I've come across. In the coming couple of weeks, I'll be getting this library to a usable state. With it's current interface, I should be able to pull over my example adapters and they should mostly work. I'll then hook those into that maze example and have a nice working example of this all. I think that'll be great to have.

[1] I have not even tried to run the code at this point. So far, I've been exploring and experimenting. I will wait to get more thoughts about our direction before proceeding too far.
[2] I still have more editing to do on this document.

[smizell]

I have added some examples of using the interface in the README. I've now tested a few parts of the interface and they are working (still need to test edge cases). The interface shouldn't change from where it is, but the underlying code is pretty primitive at this point.

I've also added in code for the translator. This code handles registering the serializers and deserializers.

I'm going to hold off here for the time being. I'll try to finish up the Hypermedia Elements doc and then I'm going take a break for a few days!

[smizell]

I've got a working copy now of the Hypermedia Resource for Python. I also hooked this into the Maze+XML I had before and split those out into two repos:

1. Maze Client
2. Maze Server

My next goal is to get a very simple adapter that outputs the Hypermedia Resource in HTML. This will make the API browseable and will really be a great way to drive home how useful this is.

In addition to having the core usable, I also have added a Hypermedia Response wrapper that receives an HTTP Accept header and a Hypermedia Resource and outputs a representation based on content negotiation (this is used in the Maze Server). I am also interested in looking at a wrapper for creating a request as well to include in the library.

[smizell]

Also, I had meant to say if you all think these maze repos are worth having under The Hypermedia Project, I'd be happy to move them here!

[mamund]

we don't need to move the repos, but maybe i will clone them into the Cj
org once they are stable.

[zdne]

if you all think these maze repos are worth having under The Hypermedia Project, I'd be happy to move them here!

We should eventually have an example API, example implementations and clients under this project, yes. Whether it is Maze or something else is to be decided I guess.

Personally, I would prefer something closer to real world API (looking at REST Fest 2014 hack day). Thoughts?

[smizell]

I think the Maze example is good, but it only has links, so there is definitely more to show. The Hack Day would be a good one to have, and if I can get a couple more things finished on the library before then, this should all be usable for Hack Day.

I have also put up the server code here:

http://maze-server.herokuapp.com/

The Python Hypermedia Resource responds with HAL, Maze+XML, and HTML (only links at this point, more support later). This shows that if you set up your resource, you get all these for free plus a browseable API. That'll be a cool example in the future.

We could also include this as AN example and not THE example. Whatever everyone things is great!