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 notifications@github.com 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 https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51012993 .

[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 notifications@github.com 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 https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51517378 .

[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 notifications@github.com 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 https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51525151 .

[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 notifications@github.com 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 .

[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 notifications@github.com 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 <notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> 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 .

[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 notifications@github.com 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 notifications@github.com 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 <notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> 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 .

[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 notifications@github.com 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 <notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> 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 <notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> 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 < notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com'); <javascript:_e(%7B%7D,'cvml','notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');');>> 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 https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51674136 .

[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 glenn.block@gmail.com 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 <notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> 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 notifications@github.com 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 notifications@github.com 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 < notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> 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 https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51674136 .

[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 notifications@github.com 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 .

[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 notifications@github.com 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 <notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> 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 .

[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 notifications@github.com 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 <notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> 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 .

[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 notifications@github.com 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 notifications@github.com 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 < notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> 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 .

[glennblock]

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

On Saturday, August 9, 2014, Mark W. Foster notifications@github.com 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 <notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> 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 <notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> 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 < notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com'); <javascript:_e(%7B%7D,'cvml','notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');');>> 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 https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51691127 .

[zdne]

I care less about naming and more about the contract

:+1:

---

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 notifications@github.com 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 https://github.com/the-hypermedia-project/charter/issues/2#issuecomment-51873316 .

[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 _.