Mutable vs Immutable Transition

[smizell]

I wanted to discuss a couple of things in Z's MSON doc. IMO, I think it's getting really close! I wanted to discuss something specifically from my other issue #7. First, here's the document.

MSON Document

Hypermedia Resource

• attributes (Collection: Attribute)
• transitions (Collection: Transition)
• meta (Meta)
• resources (Collection: Embedded Hypermedia Resource)

Attribute

• name
• value

Transition

• relation_type
• uri
• attributes (Collection: Input)
• parameters (Collection: Input)
• meta (Meta)

Input

• name
• default_value
• value

Meta

• attributes (Collection: Attribute)
• links (Collection: Transition)

Embedded Hypermedia Resource

• relation_type
• Include Hypermedia Resource

Collection: T

Generic collection, possibly with language specific implementation, array, linked list, hash etc.

Thoughts

Right now, we have the idea of a Transition and an Embedded Hypermedia Resource. I'm curious if it would be better to instead make a distinction between Mutable Transitions and Immutable Transitions instead. In the MSON above, all transitions have attributes that are inputs. In reality though, any embedded attributes on a GET request MUST be considered immutable. My thought is, not all transitions should have attributes that are considered an Input.

Additionally, (this is a personal opinion at this point) I believe that an embedded resource is a sub category of an Immutable Transition, along with the idea of a link and a query. If you look at the MSON above, you can see the similarities in the Transition and Embedded Hypermedia Resource.

If you look at my code, there is really no difference between a link and an embedded resource. A query has additional parameters, and an action has mutable attributes. I think it's important to consider all of these to be transitions, while also recognizing these different categories of transitions. This would be:

Safe, Immutable Transitions

• Links (safe method, no query params, immutable attributes)
• Queries (safe method, with query params, immutable attributes)
• Embedded Resource (safe method, no query params, immutable attributes)

Unsafe, Mutable Transitions

• Actions (unsafe methods, mutable attributes)

There would be other categories to add as well, such as templated links and templated actions. I'll leave this for discussing later.

I think these distinctions will also be important as we start building adapters. For instance, HAL only supports links and embedded resources from the listed above.

Hope this helps!

[smizell]

Just wanted to mention what I did here. I went with these categorizations in the Python library. There is a central collection of transitions that stores all of these different class types (e.g. links, queries, embedded, etc.), along with separate collections that are available for accessing these categories individually.

[zdne]

Interesting.

Embedded Resource (safe method, no query params, immutable attributes)

I might be missing something but why is that an embedded resource can't have query parameters in its URI? Or is it just saying that, while query parameters might be in its URI, they are given and thus immutable?

[smizell]

That's correct. Query params are more for something like <form method="GET">. The url for the embedded resource can have query params, though, like you said.

[smizell]

Also, just to add clarity, when I say "immutable attributes," I am differentiating between the attributes received from requesting a resource with GET, and the attributes specified for mutable transitions (e.g. an HTML with a POST method).

In other words, embedding attributes of a linked resource (either by a partially or fully embedded resource) provides immutable attributes, while including a mutable transition (such as a transition with a POST method) provides the attributes of the transition that can be changed.

Hope that makes sense! Very interested to hear other's thoughts here.

[zdne]

Hope that makes sense

Yup