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
#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 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
#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 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
#2 (comment)
.