Naming Things

[fosrias]

Up for debate/clarification/refinement:

• Organization Name other than 'The Hypermedia Project'
• This project name that will give the overview to the project, contain designs, and be reference for individual libraries implementing functionality.
• Name of "rosetta stone" class. Representor, State Object, etc.

[zdne]

Like the naming of pretty much everything including distinguishing between transition parameters (URI variables) and attributes (message-body fields).

The only possible confusion I see is when it comes to Representor attributes and Transition attributes – one an attribute (semantic descriptor) of a Resource, the other message-body field of a request. Did anyone else stumble upon this? I like the word attributes for both cases it is just we must be consistent and make sure we always address them with clear resource or transition context.

As for the organization / project name – I was (and still am) against Rosetta Stone – don't have any other name but THP (the hypermedia project), but I am pretty sure there will be some ideas here.

[fosrias]

Turns out from a profile standpoint like ALPS, attributes of transitions are themselves semantic descriptors. We have not had any trouble with this in the libraries we have been writing.

[zdne]

attributes of transitions are themselves semantic descriptors

This has never occurred to me! Great point

[smizell]

Do you all make any distinction between URI template parameters and query string parameters? In Verbose, I have all three–template params, query string params, and body params.

Thinking out loud, some URI template params always seems to be a difficult one for me in regards to defining semantics. Say for example you have the template /users/{user_id}/photos, you really want the ID of the user and not of the photo to create this URL. This feels odd that it would be considered a semantic of this particular resource. Would you consider this a semantic descriptor in ALPS?

[fosrias]

In the past, I (based on the libraries I use) have treated templated path
parameters and templated query params the same with the caveat that
templated path parameters are 'required'. Definitely keep body params
(attributes) separate.

On Sun, Aug 3, 2014 at 7:47 PM, Stephen Mizell [email protected]
wrote:

Do you all make any distinction between URI template parameters and query
string parameters? In Verbose, I have all three–template params, query
string params, and body params.

Thinking out loud, some URI template params always seems to be a difficult
one for me in regards to defining semantics. Say for example you have the
template /users/{user_id}/photos, you really want the ID of the user and
not of the photo to create this URL. This feels odd that it would be
considered a semantic of this particular resource. Would you consider this
a semantic descriptor in ALPS?

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[zdne]

In the past, I (based on the libraries I use) have treated templated path
parameters and templated query params the same with the caveat that
templated path parameters are 'required'. Definitely keep body params
(attributes) separate.

I did the same.

I totally agree on

Definitely keep body params (attributes) separate.

However as for path segment variables vs. query parameters I tend to think of them as two very different things.

[smizell]

I think in all of this, it may be helpful to have different categories or classifications of transitions. I consider links with path parameters to be a "templated" while links with only query parameters as not. Maybe there is a better name for that distinction, but a templated link is not one you can follow without some extra info, whereas a link with only query params is one you can without the parameters.

Additionally, a templated link requires some attribute of an existing resource (maybe there are exceptions), while a query param is not always an attribute and therefore may not require resource data.

Like in my example above, /users/{user_id}/photos is not a link you can follow unless you have the user_id. The link /users{?query}, though, would actually be considered a followable link because query is not necessarily required.

A little thinking out loud here.

[tfredrich]

Hi Guys! Great work and great discussion!

At the risk of being simple minded, I'm going to take a quicky left turn in regards to naming things and wondering your thoughts...

In particular, with the overarching goal to make hypermedia "...accessible to the masses." It is my opinion that we either need to teach the masses this very abstract vocabulary of the charter, or use the same language the masses do. I vote the latter--as it'll end up being much easier on us.

For example:
Representor: this is obviously something between a Resource and a Representation--the canonical in-memory representation of a resource before serialization (or after deserialization on input). Representor isn't common terminology or "ubiquitous language" and feels kinda made up and vague. Can we choose a name "the masses" would use like Resource or Representation even though it's not absolutely accurate? Or is it? HalBuilder uses the term Representation. HyperExpress uses the term Resource.

Transitions: Not very many people in my organization know what a transition is, but they completely get the concept of a link. Is it inaccurate to just call these links since we're in the context of HTTP? Or is there another not-so-generic term that "the masses" use that we can incorporate?

Another thought: Is it possible to start off simple and grow this over time? In other words, can we iterate over the design by using code as our model? Maybe support a couple of media types and grow the requirements as additional media types are added?

For example:
HyperExpress (https://github.com/RestExpress/HyperExpress) incorporates much of this concept already, supporting HAL initially with the intent to support [rudimentary] JSON-LD next.

I'm excited to see where this conversation goes and how HyperExpress can morph towards what we define here.

[smizell]

I do like the idea of the API using some common terminologies, thought I also think, maybe this is a chance to educate? For the sake of quick adoption, though, common terms seems to be the way to go (hence using "links" in my maze example).

Like you're saying as well, that doesn't mean this terminology can't be a veil to the underlying model. A link is a transition, but it's usually considered a certain kind of transition (a safe, idempotent request) by the masses. An action is similar, as it conveys different aspects of a transition. The underlying model may classify everything as a transition, though the API may provide something like resource.links that gives transitions in the link category, which would basically be all the link relations and their URLs.

Regarding "Representer," I wonder if we could still refer to the model conceptually as representer, but call it something else at the same time. For example, my library is called Halpert, and a Halpert object is a representer object. Is there some ambiguous, made-up name we could call this object for the masses, though still classify it as a representer? Something we could name it across all these languages instead of us all coming up with our own names?

Just some thinking out loud here.

[kevinswiber]

Like you're saying as well, that doesn't mean this terminology can't be a veil to the underlying model. A link is a transition, but it's usually considered a certain kind of transition (a safe, idempotent request) by the masses. An action is similar, as it conveys different aspects of a transition. The underlying model may classify everything as a transition, though the API may provide something like resource.links that gives transitions in the link category, which would basically be all the link relations and their URLs.

The term "transition" has multiple contexts. Based on feedback I heard at the recent API Craft Conference, this can be confusing to many people.

In an API interaction, there may be both client state transitions and resource state transitions.

Making any request will result in a transition of client state (sometimes called application state). Making an unsafe request can result in a transition of resource state.

We need to be careful not to conflate these concepts.

[smizell]

We need to be careful not to conflate these concepts.

That's a good point, and I think this is super helpful to think around all the edges of these projects.

I think we should also not think of this representer object as a client, but rather as a component/element of the client. The representer primarily is an interface to the representation of the resource (on the client side in the case I'm speaking of here). It does not deal with client/application state in anyway, which would all be handled up the ladder. To the representer, transitions will always be resource state transitions, IMO. Thoughts?

[fosrias]

I do like the idea of the API using some common terminologies

So, I think we need to find a compromise here between how people SHOULD think about this and what they are capable of grasping. Per @tfredrich's comment on transitions, it is true that developers don't grok simple finite state-machines. This is not a good thing:

• http://research.microsoft.com/en-us/um/people/lamport/pubs/state-machine.pdf
• http://www.shopify.com/technology/3383012-why-developers-should-be-force-fed-state-machines
• http://www.skorks.com/2011/09/why-developers-never-use-state-machines/

We may not be in the business here of winning that battle, but frankly this type of interface for introspecting a hypermedia message is much closer to the truth IMO. Thus, I think we need to provide an interface and teach people how to use it as part of this process that breaks old thought patterns, while at the same time helping them get past their mental blocks (see example of different style of thinking and coding below we want to reinforce).

However, as @kevinswiber points out, understanding the difference between application state and resource state transitions is important. From a state-machine interface these are transparent, which in one sense is a benefit to me. That is, if a client "understands" what the transition does, it can use it to modify a resource or change client (application state) or take a peak at another resource, etc. You just have avail to transition state presented to you in the resource.

So, not sure that calling it conflates this since one SHOULD understand this (but I was listening to the confusion about this at during the panel so understand we need to be sensitive to it).

I think using the term "links" over simplifies things. I think having "links" and "actions/forms" as separate concepts, though possibly useful in a media-type does not add extra in terms of the interface we are trying to surface here in that a client would have to look for different things.

If we take a step back and thing that hypermedia is about "data" and "controls", if we did not want to use the term "transitions", I think we could maybe discuss "controls" or make that an alias for "transitions". You can then have different types of controls. Some are "link" controls and some are "action/form-like" controls. They are not "methods" because we are not going RPC and are fending off OOP thinking.

W/r to "Representor" (I name this a little differently than @smizell, but it is conceptually the same), I like that name for a number of reasons as it more re-enforces an idea about how one should look at a message. I could go with something like "StateRepresentation" ala @glennblock's "StateObject". I don't think "Resource" is a good name because it is more mis-leading IMO.

Some ruby pseudo code to highlight why I think we should strive to keep this really simple and state-machine centric:

some_resource_representor = agent.enter('https://example.org/some_resource')

transitions = some_resource_representor.transitions
desired_transition = transitions['the_one_i_want']

# No RPC here and this type of coding keeps things loosely coupled and evolvable
if transition
  transition.apply_attributes(params['attributes']) if transition.attributes? 
  transition. invoke
else
  # I write my code to recover or pick an alt. path, etc.
end

Alt. using controls

some_resource_representor = agent.enter('https://example.org/some_resource')

controls = some_resource_representor.controls
desired_control = controls['the_one_i_want']

# No RPC here and this type of coding keeps things loosely coupled and evolvable
if control
  control.apply_attributes(params['attributes']) if control.attributes? 
  control. invoke
else
  # I write my code to recover or pick an alt. path, etc.
end

If we keep this simple and don't capitulate to a OOP/Remote Type Mashalling interface, I think we get a win.

Also, as much as we are doing all this to make it workable for others, we are threading the balance of doing this so we can use it ourselves and leverage this tooling in our work, so I think we need to balance that as well.

[smizell]

Great thoughts, Mark. So I guess the question that you're getting to is,
how do we get other developers thinking about getting form point A (links,
actions, methods) to point B (state transitions)? What is a good first step
to get adoption yet push developers along? Keeping these transitions
separate doesn't seem like the best long term move. If we see it as
important to have links/actions available, we could provide methods that
filter out transitions based on certain criteria. That would mean we'd have
to define exactly what a link or action is.

On Thu, Aug 7, 2014 at 2:08 PM, Mark W. Foster [email protected]
wrote:

I do like the idea of the API using some common terminologies

So, I think we need to find a compromise here between how people SHOULD
think about this and what they are capable of grasping. Per @tfredrich
https://github.com/tfredrich's comment on transitions, it is true that
developers don't grok simple finite state-machines. This is not a good
thing:

http://research.microsoft.com/en-us/um/people/lamport/pubs/state-machine.pdf

http://www.shopify.com/technology/3383012-why-developers-should-be-force-fed-state-machines

http://www.skorks.com/2011/09/why-developers-never-use-state-machines/

We may not be in the business here of winning that battle, but frankly
this type of interface for introspecting a hypermedia message is much
closer to the truth IMO. Thus, I think we need to provide an interface and
teach people how to use it as part of this process that breaks old thought
patterns, while at the same time helping them get past their mental blocks
(see example of different style of thinking and coding below we want to
reinforce).

However, as @kevinswiber https://github.com/kevinswiber points out,
understanding the difference between application state and resource state
transitions is important. From a state-machine interface these are
transparent, which in one sense is a benefit to me. That is, if a client
"understands" what the transition does, it can use it to modify a resource
or change client (application state) or take a peak at another resource,
etc. You just have avail to transition state presented to you in the
resource.

So, not sure that calling it conflates this since one SHOULD understand
this (but I was listening to the confusion about this at during the panel
so understand we need to be sensitive to it).

I think using the term "links" over simplifies things. I think having
"links" and "actions/forms" as separate concepts, though possibly useful in
a media-type does not add extra in terms of the interface we are trying to
surface here in that a client would have to look for different things.

If we take a step back and thing that hypermedia is about "data" and
"controls", if we did not want to use the term "transitions", I think we
could maybe discuss "controls" or make that an alias for "transitions". You
can then have different types of controls. Some are "link" controls and
some are "action/form-like" controls. They are not "methods" because we are
not going RPC and are fending off OOP thinking.

W/r to "Representor" (I name this a little differently than @smizell
https://github.com/smizell, but it is conceptually the same), I like
that name for a number of reasons as it more re-enforces an idea about how
one should look at a message. I could go with something like
"StateRepresentation" ala @glennblock https://github.com/glennblock's
"StateObject". I don't think "Resource" is a good name because it is more
mis-leading IMO.

Some ruby pseudo code to highlight why I think we should strive to keep
this really simple and state-machine centric:

some_resource_representor = agent.enter("https://example.org/some_resource')
transitions = some_resource_representor.transitionsdesired_transition = transitions['the_one_i_want"]

No RPC here and this type of coding keeps things loosely coupled and evolvableif transition

transition.apply_attributes(params['attributes']) if transition.attributes?
transition. invokeelse

I write my code to recover or pick an alt. path, etc.end

Alt. using controls

some_resource_representor = agent.enter("https://example.org/some_resource')
controls = some_resource_representor.controlsdesired_control = controls['the_one_i_want"]

No RPC here and this type of coding keeps things loosely coupled and evolvableif control

control.apply_attributes(params['attributes']) if control.attributes?
control. invokeelse

I write my code to recover or pick an alt. path, etc.end

If we keep this simple and don't capitulate to a OOP/Remote Type
Mashalling interface, I think we get a win.

Also, as much as we are doing all this to make it workable for others, we
are threading the balance of doing this so we can use it ourselves and
leverage this tooling in our work, so I think we need to balance that as
well.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[fosrias]

Well, per @tfredrich's comment above, maybe we start off simple and just do the simple finite state-machine interface and proof test if it really is a WTF for developers when they see it with some sample code, etc. We could go round an round, but I have actually worked on this with other devs and I am not sure it will be such a barrier.

If we feel we need more separation, what that is would be more clear down the road. In the end of the day, what we are working on here is a simple interface that abstracts the requirement of knowing messages and protocols (ideally) and allowing task based interaction with messages. I think the initial proposed interface in the Charter README is workable to start and we can evolve in concert as each of us gets this in the hands of other devs. That would be my 2-bits and I think would get us moving faster.

[smizell]

That sounds great to me personally. The code sample idea is a good one,
too. We'll need to show some real-world examples of how this really is
helpful.

I have the maze example [1] and I'll work on changing the terminology there
to match your proposed interface.

[1] https://github.com/smizell/maze_client

On Thu, Aug 7, 2014 at 3:13 PM, Mark W. Foster [email protected]
wrote:

Well, per @tfredrich https://github.com/tfredrich's comment above,
maybe we start off simple and just do the simple finite state-machine
interface and proof test if it really is a WTF for developers when they see
it with some sample code, etc. We could go round an round, but I have
actually worked on this with other devs and I am not sure it will be such a
barrier.

If we feel we need more separation, what that is would be more clear down
the road. In the end of the day, what we are working on here is a simple
interface that abstracts the requirement of knowing messages and protocols
(ideally) and allowing task based interaction with messages. I think the
initial proposed interface in the Charter README is workable to start and
we can evolve in concert as each of us gets this in the hands of other
devs. That would be my 2-bits and I think would get us moving faster.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[mamund]

all:

great to be able to follow this discussion here.

i started using the term "representor" a while back and always had as a "to-do item" to check into the GoF patterns to see if there isn't an already (better) established name for this code pattern.

maybe this is better referred to as the bridge pattern or the mediator pattern. or some other more recent invention like the Model-View-Presenter pattern.

just adding this to get people thinking. would be a bummer to reinvent something that is already well-defined and widely understood.

[MatthewReinbold]

Well-defined, perhaps. Widely understood is subjective and depends on the audience. The initial charter references "for the masses". The terminology is still at such a high (and abstract) level that the compelling elevator pitch of the project's relevance isn't there yet.

[fosrias]

The relevance, IMO, is not going to be just that we got all the terminology
correct, but more importantly the demonstration of the technology. We can
work on the terminology along the way. It is abstract ATM. Once things are
working, it will be far from abstract if we accomplish the goals.

On Fri, Aug 8, 2014 at 2:29 PM, MatthewReinbold [email protected]
wrote:

Well-defined, perhaps. Widely understood is subjective and depends on the
audience. The initial charter references "for the masses". The terminology
is still at such a high (and abstract) level that the compelling elevator
pitch of the project's relevance isn't there yet.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[glennblock]

We deliberately skirted away from View
Model in our book as though it is an established pattern, it is overloaded
with a Ui context. I have done a lot of work with View Models / MVP over
the years and it was always for servicing the UI / that is where he pattern
was born.

For that reason I avoid using it.

We came up with the term State Model to specifically connote that the
purpose of the model is to transfer app and resource state.

On Friday, August 8, 2014, Mark W. Foster [email protected] wrote:

The relevance, IMO, is not going to be just that we got all the
terminology
correct, but more importantly the demonstration of the technology. We can
work on the terminology along the way. It is abstract ATM. Once things are
working, it will be far from abstract if we accomplish the goals.

On Fri, Aug 8, 2014 at 2:29 PM, MatthewReinbold <[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');>
wrote:

Well-defined, perhaps. Widely understood is subjective and depends on
the
audience. The initial charter references "for the masses". The
terminology
is still at such a high (and abstract) level that the compelling
elevator
pitch of the project's relevance isn't there yet.

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

.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[kevinswiber]

While I do like StateModel, it can be too loosely defined when introducing
differences between read and write.

I've used terms like ReadModel and WriteModel in the past.

Sent from my iPhone

On Aug 8, 2014, at 9:57 PM, Glenn Block [email protected] wrote:

We deliberately skirted away from View
Model in our book as though it is an established pattern, it is overloaded
with a Ui context. I have done a lot of work with View Models / MVP over
the years and it was always for servicing the UI / that is where he pattern
was born.

For that reason I avoid using it.

We came up with the term State Model to specifically connote that the
purpose of the model is to transfer app and resource state.

On Friday, August 8, 2014, Mark W. Foster [email protected] wrote:

The relevance, IMO, is not going to be just that we got all the
terminology
correct, but more importantly the demonstration of the technology. We can
work on the terminology along the way. It is abstract ATM. Once things
are
working, it will be far from abstract if we accomplish the goals.

On Fri, Aug 8, 2014 at 2:29 PM, MatthewReinbold <[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');>
wrote:

Well-defined, perhaps. Widely understood is subjective and depends on
the
audience. The initial charter references "for the masses". The
terminology
is still at such a high (and abstract) level that the compelling
elevator
pitch of the project's relevance isn't there yet.

—
Reply to this email directly or view it on GitHub
<

https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51659919>

.

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

.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[glennblock]

I am not stuck on StateModel, my bigger point was not to use ViewModel ;-)

As to Read vs Write are you saying Read is something returned VS something
that is sent?

On Friday, August 8, 2014, Kevin Swiber [email protected] wrote:

While I do like StateModel, it can be too loosely defined when introducing
differences between read and write.

I've used terms like ReadModel and WriteModel in the past.

Sent from my iPhone

On Aug 8, 2014, at 9:57 PM, Glenn Block <[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');> wrote:

We deliberately skirted away from View
Model in our book as though it is an established pattern, it is overloaded
with a Ui context. I have done a lot of work with View Models / MVP over
the years and it was always for servicing the UI / that is where he
pattern
was born.

For that reason I avoid using it.

We came up with the term State Model to specifically connote that the
purpose of the model is to transfer app and resource state.

On Friday, August 8, 2014, Mark W. Foster <[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');> wrote:

The relevance, IMO, is not going to be just that we got all the
terminology
correct, but more importantly the demonstration of the technology. We
can
work on the terminology along the way. It is abstract ATM. Once things
are
working, it will be far from abstract if we accomplish the goals.

On Fri, Aug 8, 2014 at 2:29 PM, MatthewReinbold <
[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');
<javascript:_e(%7B%7D,'cvml','[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');');>>
wrote:

Well-defined, perhaps. Widely understood is subjective and depends on
the
audience. The initial charter references "for the masses". The
terminology
is still at such a high (and abstract) level that the compelling
elevator
pitch of the project's relevance isn't there yet.

—
Reply to this email directly or view it on GitHub
<

https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51659919>

.

—
Reply to this email directly or view it on GitHub
<

https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51661918>

.

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

.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[glennblock]

Just to add to the name game, Darrel likes
to use InformationModel.

Also I guess we could consider RequestModel and ResponseModel.

As long as if is not RestModel :-)

On Friday, August 8, 2014, Glenn Block [email protected] wrote:

I am not stuck on StateModel, my bigger point was not to use ViewModel ;-)

As to Read vs Write are you saying Read is something returned VS something
that is sent?

On Friday, August 8, 2014, Kevin Swiber <[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');> wrote:

While I do like StateModel, it can be too loosely defined when
introducing
differences between read and write.

I've used terms like ReadModel and WriteModel in the past.

Sent from my iPhone

On Aug 8, 2014, at 9:57 PM, Glenn Block [email protected]
wrote:

We deliberately skirted away from View
Model in our book as though it is an established pattern, it is
overloaded
with a Ui context. I have done a lot of work with View Models / MVP over
the years and it was always for servicing the UI / that is where he
pattern
was born.

For that reason I avoid using it.

We came up with the term State Model to specifically connote that the
purpose of the model is to transfer app and resource state.

On Friday, August 8, 2014, Mark W. Foster [email protected]
wrote:

The relevance, IMO, is not going to be just that we got all the
terminology
correct, but more importantly the demonstration of the technology. We
can
work on the terminology along the way. It is abstract ATM. Once things
are
working, it will be far from abstract if we accomplish the goals.

On Fri, Aug 8, 2014 at 2:29 PM, MatthewReinbold <
[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');>
wrote:

Well-defined, perhaps. Widely understood is subjective and depends on
the
audience. The initial charter references "for the masses". The
terminology
is still at such a high (and abstract) level that the compelling
elevator
pitch of the project's relevance isn't there yet.

—
Reply to this email directly or view it on GitHub
<

https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51659919>

.

—
Reply to this email directly or view it on GitHub
<

https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51661918>

.

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

.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[MatthewReinbold]

I like RequestModel and ResponseModel - descriptive enough that even introductory API types can grok what they are about while simultaneously noting that they are an abstraction, a representation.

[fosrias]

I don't see having two classes. Further, I don't like the use of "Model" as
it leans towards feeling like type marshalling. All that being said, I
could go with "MessageObject". We are creating an object that wraps a
hypermedia message. I think it is tractable. Or, "HypermediaMessageObject",
but to me the latter is overly verbose, but pretty explicit. Or, possibly
shorter "HypermediaObject".

However, the idea of "transitions" and finite state-machine don't map as
well with a "MessageObject" or the others per se. However, "controls" may
work per my comment earlier in the thread.

If we felt this needed something more technical, then I would vote
"ResponseObject" if we feel "Representor" is to abstract. But per @mamund's
comment, I want to poke around with design patterns a bit. I looked at the
patterns he mentioned. Not sure this is the "mediator" even though that may
be close.

However, I think there is a lot to be gained by not moving away from a
simple finite state-machine interface and an object name the re-enforces
that.

On Fri, Aug 8, 2014 at 9:26 PM, MatthewReinbold [email protected]
wrote:

I like RequestModel and ResponseModel - descriptive enough that even
introductory API types can grok what they are about while simultaneously
noting that they are an abstraction, a representation.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[glennblock]

The model is not marshaled, the model is used to carry data and links which
are then represented in some format. I agree we don't want to encourage
type marshaling, but that is not the usage of the model I am suggesting.

On Friday, August 8, 2014, Mark W. Foster [email protected] wrote:

I don't see having two classes. Further, I don't like the use of "Model"
as
it leans towards feeling like type marshalling. All that being said, I
could go with "MessageObject". We are creating an object that wraps a
hypermedia message. I think it is tractable. Or,
"HypermediaMessageObject",
but to me the latter is overly verbose, but pretty explicit. Or, possibly
shorter "HypermediaObject".

However, the idea of "transitions" and finite state-machine don't map as
well with a "MessageObject" or the others per se. However, "controls" may
work per my comment earlier in the thread.

If we felt this needed something more technical, then I would vote
"ResponseObject" if we feel "Representor" is to abstract. But per
@mamund's
comment, I want to poke around with design patterns a bit. I looked at the
patterns he mentioned. Not sure this is the "mediator" even though that
may
be close.

However, I think there is a lot to be gained by not moving away from a
simple finite state-machine interface and an object name the re-enforces
that.

On Fri, Aug 8, 2014 at 9:26 PM, MatthewReinbold <[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');>
wrote:

I like RequestModel and ResponseModel - descriptive enough that even
introductory API types can grok what they are about while simultaneously
noting that they are an abstraction, a representation.

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

.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[glennblock]

I don't think if is a mediator pattern. A mediator is something that is
active, which listens to events and coordinates between other objects.

On Friday, August 8, 2014, Mark W. Foster [email protected] wrote:

I don't see having two classes. Further, I don't like the use of "Model"
as
it leans towards feeling like type marshalling. All that being said, I
could go with "MessageObject". We are creating an object that wraps a
hypermedia message. I think it is tractable. Or,
"HypermediaMessageObject",
but to me the latter is overly verbose, but pretty explicit. Or, possibly
shorter "HypermediaObject".

However, the idea of "transitions" and finite state-machine don't map as
well with a "MessageObject" or the others per se. However, "controls" may
work per my comment earlier in the thread.

If we felt this needed something more technical, then I would vote
"ResponseObject" if we feel "Representor" is to abstract. But per
@mamund's
comment, I want to poke around with design patterns a bit. I looked at the
patterns he mentioned. Not sure this is the "mediator" even though that
may
be close.

However, I think there is a lot to be gained by not moving away from a
simple finite state-machine interface and an object name the re-enforces
that.

On Fri, Aug 8, 2014 at 9:26 PM, MatthewReinbold <[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');>
wrote:

I like RequestModel and ResponseModel - descriptive enough that even
introductory API types can grok what they are about while simultaneously
noting that they are an abstraction, a representation.

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

.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[fosrias]

@glennblock My comment on marshalling had to do with in no way
communicating that the model tied to any remote data model (as that is part
of what we need to mentally shift in the space, IMO). Probably an over
reaction.

That being said, I could go with "ResponseModel" or "ResponseObject" in
that it is the local model/instance of a response and allows interacting
with a hypermedia response (frankly, if we do this right, it will work with
application/json too). That works fine client-side conceptually. Further,
if we use this object service-side to generate responses, it still works
conceptually IMO.

Also, I did pretty fast cursory review of design patterns and don't think
there is one that translates to what we are doing. Mediator is the only one
that is close, but concur on your assessment.

On Sat, Aug 9, 2014 at 6:57 AM, Glenn Block [email protected]
wrote:

I don't think if is a mediator pattern. A mediator is something that is
active, which listens to events and coordinates between other objects.

On Friday, August 8, 2014, Mark W. Foster [email protected]
wrote:

I don't see having two classes. Further, I don't like the use of "Model"
as
it leans towards feeling like type marshalling. All that being said, I
could go with "MessageObject". We are creating an object that wraps a
hypermedia message. I think it is tractable. Or,
"HypermediaMessageObject",
but to me the latter is overly verbose, but pretty explicit. Or,
possibly
shorter "HypermediaObject".

However, the idea of "transitions" and finite state-machine don't map as
well with a "MessageObject" or the others per se. However, "controls"
may
work per my comment earlier in the thread.

If we felt this needed something more technical, then I would vote
"ResponseObject" if we feel "Representor" is to abstract. But per
@mamund's
comment, I want to poke around with design patterns a bit. I looked at
the
patterns he mentioned. Not sure this is the "mediator" even though that
may
be close.

However, I think there is a lot to be gained by not moving away from a
simple finite state-machine interface and an object name the re-enforces
that.

On Fri, Aug 8, 2014 at 9:26 PM, MatthewReinbold <
[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');>
wrote:

I like RequestModel and ResponseModel - descriptive enough that even
introductory API types can grok what they are about while
simultaneously
noting that they are an abstraction, a representation.

—
Reply to this email directly or view it on GitHub
<

https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51676827>

.

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

.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[glennblock]

Cool, I care less about naming and more about the contract :-)

On Saturday, August 9, 2014, Mark W. Foster [email protected]
wrote:

@glennblock My comment on marshalling had to do with in no way
communicating that the model tied to any remote data model (as that is
part
of what we need to mentally shift in the space, IMO). Probably an over
reaction.

That being said, I could go with "ResponseModel" or "ResponseObject" in
that it is the local model/instance of a response and allows interacting
with a hypermedia response (frankly, if we do this right, it will work
with
application/json too). That works fine client-side conceptually. Further,
if we use this object service-side to generate responses, it still works
conceptually IMO.

Also, I did pretty fast cursory review of design patterns and don't think
there is one that translates to what we are doing. Mediator is the only
one
that is close, but concur on your assessment.

On Sat, Aug 9, 2014 at 6:57 AM, Glenn Block <[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');>
wrote:

I don't think if is a mediator pattern. A mediator is something that is
active, which listens to events and coordinates between other objects.

On Friday, August 8, 2014, Mark W. Foster <[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');>
wrote:

I don't see having two classes. Further, I don't like the use of
"Model"
as
it leans towards feeling like type marshalling. All that being said, I
could go with "MessageObject". We are creating an object that wraps a
hypermedia message. I think it is tractable. Or,
"HypermediaMessageObject",
but to me the latter is overly verbose, but pretty explicit. Or,
possibly
shorter "HypermediaObject".

However, the idea of "transitions" and finite state-machine don't map
as
well with a "MessageObject" or the others per se. However, "controls"
may
work per my comment earlier in the thread.

If we felt this needed something more technical, then I would vote
"ResponseObject" if we feel "Representor" is to abstract. But per
@mamund's
comment, I want to poke around with design patterns a bit. I looked at
the
patterns he mentioned. Not sure this is the "mediator" even though
that
may
be close.

However, I think there is a lot to be gained by not moving away from a
simple finite state-machine interface and an object name the
re-enforces
that.

On Fri, Aug 8, 2014 at 9:26 PM, MatthewReinbold <
[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');
<javascript:_e(%7B%7D,'cvml','[email protected]
javascript:_e(%7B%7D,'cvml','[email protected]');');>>
wrote:

I like RequestModel and ResponseModel - descriptive enough that even
introductory API types can grok what they are about while
simultaneously
noting that they are an abstraction, a representation.

—
Reply to this email directly or view it on GitHub
<

https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51676827>

.

—
Reply to this email directly or view it on GitHub
<

https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51677384>

.

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

.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[zdne]

I care less about naming and more about the contract

👍

---

Shall we move on? @fosrias would you kick of some initial form of contract or is there still something that needs to be discussed?

[fosrias]

@zdne Been wondering the same thing. I think we can sort out naming, etc.
further along the way. We have started an interface in
https://github.com/mdsol/representors but there is no documentation yet. If
you think it is reasonable, I can surface that interface here as a starting
point for discussion.

On Mon, Aug 11, 2014 at 9:48 PM, Z [email protected] wrote:

I care less about naming and more about the contract

• 1

---

Shall we move on? @fosrias https://github.com/fosrias would you kick of
some initial form of contract or is there still something that needs to be
discussed?

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[zdne]

@fosrias I think an initial version of representor interface in Ruby (or any other language) would go a long way!

[fosrias]

@zdne @smizell @glennblock @tfredrich @tedepstein @mamund Per Z's prompting, I put together the following for discussion of an interface for the object in ruby (with rubyisms in its implementation):

https://github.com/the-hypermedia-project/hypermedia_resource

I used the name "HypermediaResource" as the class name just as another variation to think about. It is not written as a gem with TDD (I have implemented a similar interface in a different library). It is more that @zdne felt it would be useful to just see some code. So, I put it together.

[fosrias]

Per feedback from @zdne, renamed to:

https://github.com/the-hypermedia-project/hypermedia-resource-ruby

With the future convention of -language in the repos for the libaries (e.g. hypermedia-resource-swift, hypermedia-resource-java, etc.). Note the use of dashes throughout vs. using _.