Resource Namespace

[zdne]

This namespaces extend MSON namespace with elements necessary to build REST Resource description / definition object model.

To be clarified:

• Use dash versus camelCase in element types names (data-structure vs dataStructure),

  A: Use camelCase

• Transition: Is content of Transition element an array of Transaction examples elements or Transition's parameters and attributes?

  A: parmaters and attributes to stay under attributes property, Transactions examples are the content

• HTTP Message: Are assets with a message content or attributes (think about JSON, JSON Schema, binary blobs being sent etc)?

  Note: in a future I can see arbitrary assets to be associated with more elements (resource, data structure etc).

  A: Asset as well as data structure are part of the element content

• Asset: Is using class in meta to distinguish classification of an asset like this correct?

  A: It is OK as it is.

---

NOTE: This namespace defines elements necessary for definition / description of a REST resource – not necessarily for capturing a resource representational message.

---

This PR supersedes #8 and #11 .

[smizell]

It may be helpful to address issue #12 first before committing to this, as you may be able to do what you originally had planned, which was to put href, parameters, and attributes in the attributes section, along with content being defined as an array of Transaction elements. Would that simplify this any?

[zdne]

@kylef @danielgtaylor @smizell: I have updated PR. I believe it now captures all the information I wanted (to be able to convert API Blueprint (resource subtree) AST into it.

I am up for any simplification or clarification!

Please let me know. Also see my TODO items on PR description and let me know what you think.

Thanks!

---

_Lets' finish this one! _ 🍨

[smizell]

Do these need required on them in some way?

[smizell]

As I was pressing comment, I noticed fixed. I guess this covers it?

[zdne]

As I was pressing comment, I noticed fixed. I guess this covers it?

Yup. That "fixes" the content of the property.

[smizell]

Thoughts on your questions

Use dash versus camelCase in element types names

I personally think dashes or more readable, but I think camelCase is probably a safer bet with the JavaScript/JSON world, so I would vote camelCase.

Transition: Is content of Transition element an array of Transaction examples elements or Transition's parameters and attributes?

Feels like you have it right with content of transitions being transactions with parameters and attributes being in attributes.

HTTP Message: Are assets with a message content or attributes (think about JSON, JSON Schema, binary blobs being sent etc)?

I could have read this question incorrectly, but it seems like the content of an HTTP message could either be a string (where the content-type defines how it should be parsed) or an element (where the content of that element dictates how it is handled). This means the content of application/json could either be a normal string like "{ \"foo\": \"bar\" }" or:

{
  "element": "json",
  "content": {
    "foo": "bar"
  }
}

Then you could have multipart elements that combine these elements or whatever. Now, you don't need to define those elements here and now, but it could be an interesting pattern to think through.

Asset: Is using class in meta to distinguish classification of an asset like this correct?

I think you can use class however you see fit. Makes for creating multi-purpose elements IMO. What would the tradeoffs be for this versus defining a new element?

Thoughts of my own

First impressions. Thought it might be helpful to you to get that perspective.

• The HTTP Message confused me because it seems like a central conept, but was never really used because it's a base for other elements. Would you lose anything by just moving those attributes to request/response elements and not having this inheritance?
• Having href every where was a little confusing as well. In some places it was a template that had parameters, some places not.
• At a quick glance, the term parameters and attributes do not seem different to me.
• How are attributes of a transition considered to be "inputs" for a transition? I wasn't for sure what that meant.
• Does href propogate down to transitions and transactions (like it does for resources and actions in API Blueprint)?
• When you have the relation attribute, what is it related to? It says the current resource, but there isn't really a current resource in this, IMO.

My first reaction to really digging in here is that this was hard to understand for me. I understood what a resource was (I think). Transitions with transactions, though, did not map well in my head. When working with a resource, I usually think of the actions you can take on it. I also think of how it relates to other resources. These seem to both be grouped under the same idea of "Transitions."

I don't want to hold this up, because it sounds like this will work for you, though something feels off to me. I can't quite nail down what that is or what a solution would be, so I'll think on it some more. I think the thing that is throwing me off most is href templates and normal hrefs in several elements.

[smizell]

More thinking out loud here if that's ok. It seems like you have these elements, which mostly mimic the current API Blueprint.

• resource
  • action (something you do to the parent resource)
    • examples (collection of transactions)
  • relation (something you do to another resource)
    • examples (collection of transactions)

['resource', { 'title': 'My resource' }, { 'href': '/asdf' }, [
  ['action', { 'title': 'Retrieve' }, { 'method': 'GET'}, null],
  ['relation', { 'title': 'Retrieve related resource'}, { 'href': '/jkl', 'method': 'GET' }, null]
]]

This would mean there are these constraints to define:

• Both resources and actions can define URI parameters (Href variables)
• Actions do not have their own URL (Href) because they are actions taken on the parent resource
• A relation is actually a resource + action, so it has its own Href and method. You COULD make this a nested resource that has only one action and simplify even more.

Not saying you have to do this, but just saying how I categorize these in my head. I suppose this is simply breaking apart the idea of a "transition," but in doing so you surface the constraints I listed above. Otherwise you have to introspect things and figure out what constraints to apply and when to apply them.

[danielgtaylor]

Do you think it is worth trying to capture responses that have multiple status codes, i.e. HTTP 100 Continue? Urban Airship disabled the feature due to problems it was causing, but I know for a fact that Amazon S3 supports it and it's a commonly used pattern for APIs that handle large message bodies.

On the one hand I feel like it's an implementation detail not relevant to the higher level final request/response pair, on the other it seems important to include in the request/response examples so that implementers are aware of the feature.

Sample response: http://www.jmarshall.com/easy/http/#http1.1c4

[zdne]

That is a very interesting point @danielgtaylor ! I think I would leave it as is for now. If needed later I think we can allow either two responses and or add an array like statusCodes.

[zdne]

@kylef @smizell @danielgtaylor

This is ready to be reviewed and merged. Let me know your thoughts!

Note I went through most of the comments @smizell had here #13 (comment) and here #13 (comment) with Stephen.

I hope I've addressed most of them.

Regarding transition vs action & relation – I recognize the transition as a "base element" to action (current resource bound transition) and relation (transition to another resource). However I believe for our purposes we shouldn't be distinguishing these two – simply because at a resource design time you may not have enough information to decide this. Consider:

## Resource Gist

### Attributes
+ id
+ description
+ content
+ created_at
+ author
    + name

### Affordances
+ show 
+ edit
+ delete
+ archive
+ restore
+ author

Which of those affordances is transition to another resource (=relations) and which one is state transition on the same resource (=action)?

---

In any case I am open to comments and suggestions!

Thanks!

[danielgtaylor]

Camel casing?

[zdne]

Fixed camelCase. Any other comments @smizell @kylef ?

[smizell]

Just thought of this. Would it help to clarify that if the href is not present, these parameters SHOULD be used for the parent resource href?

[zdne]

@smizell addressed & squashed

[kylef]

Missing trailing full stop on a few of the properties such as the above. Only pointing out because some have a full-stop and it's inconsistent. But not really a blocking problem.

• statusCode (number) - HTTP response status code.

[kylef]

👍 from me.

[smizell]

@zdne I like what you did with the href stuff 👍

[pksunkara]

Why is this called parameters but the one under resource is called hrefVariables?

[zdne]

Semantically, the two are different.

Let's start with transition: Any transition may have input properties (refer to representor charter) those properties are either parameters or attributes. In addition to that – since a templated href can be provided – you can have some other variables in there.

Consider resource "friends" which is an array of friend resources every user have. Its templated href may be something like /user/{username}/friends. Now if you are "sitting" on the Friends resource you can perhaps take a transition list that lists all the friends. Let's say the transition parameter is limit to limit maximum number of friend resources returned. The full templated href would look like /user/{username}/friends{?limit}.

You can see that username and limit are input parameters of the transition. In a resource context, those are not necessarily parameters.

Now, strictly speaking, the parameter of the list transition is really just a limit (not username) because in a hypermedia system the value of username should be already resolved by now.

So in theory the transition should have both hrefVariables and parameters. I didn't want to overcomplicate things introducing both here but I've wanted to at least acknowledge this fact.

Does this make sense?

[pksunkara]

Yes. I guess we should wait and see for adding the parameters at resource level.