Python Hypermedia Resource #7
Description
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.