"is:issue-query" vs "is:add-issue"

[mooreniemi]

One thing that makes serialization a little trickier is that the "is" keys don't all follow an order. I'd expected them to be roughly: is:resource_name-action or is:action-resource_name but not both. In my implementation I will probably support just one. Can one become preferred? (I'm probably going to go with essentially is:verb-direct_object.)

[JornWildt]

I am not sure about what you are trying to here - but those identifiers are link relations and as such they have no semantics attached to the textual structure. Link relations can be of just about any form - those are just examples I chose for the demo.

Making a serialization that depends on the link rel textual structure seems very wrong to me.

Remember that "is" is a namespace prefix as used in XML which means it should be expanded to its full URI before evaluation (the related URI base is defined in the "@meta" element). Check "CURIES" in the Mason specification.

[mooreniemi]

@JornWildt Well, here's where it's coming up for me: I want to generate Mason responses from Ruby objects. Ideally, I'd like to not have to specify the name of each link rel, and if they all follow a convention I can easily reflect on the object and action and infer them directly:

 64     def action_template(params)
 65       {
 66         "is:#{params[:name]}-#{resource_name_of(serializer.object).singularize}" => params.except(:name).merge!(
 67           {
 68             href: get_url_for(params[:name])
 69           }
 70         )
 71       }
 72     end

[mooreniemi]

For posterity, I'm thinking this through here though I think I understand what you meant before @JornWildt.

Looking at:

 8   "@namespaces": {
 9     "is": {
 10       "name": "http://localhost:9292/rels#"
 11     }
 12   },

and

 17     "is:filter": {

gets expanded to "http://localhost:9292/rels#filter" right? (Haven't worked with CURIEs before, but following: http://crosstech.crossref.org/2008/12/curies_a_cure_for_uris.html).

Thing is, if I have a pre-JSON object, say in Ruby, and I want to translate it into JSON, I will prob want some conventions around that translation. So say I have generic object like "submissions" -- it doesn't look from the example like I have a separate namespace for it, right? Which is why in the link relations we see stuff like "update-issue" etc? My initial feeling was ok, if I'm serializing a Ruby object into JSON, do namespace:action-resource_name. This isn't a concern for Mason though, it's really just a concern for me implementing serializers.

[mooreniemi]

Oh I did have one question though -- the namespace, it's totally arbitrary, yes? "is" is just short for "issue" and not actually meant to mean "this is x", yeah? I think I read too much meaning into that!

[mooreniemi]

1 {
2   "title": "View submissions",
3   "description": "idk yet",
4   "@meta": {
5     "@title": "Submissions",
6     "@description": "This resource represents submissions."
7   },
8   "@namespaces": {
9     "submissions": {

Can I have more than one namespace? Do they link to entirely different pages? I'm assuming yes.

10       "name": "http://localhost:9292/rels#"
11     }
12   },
13   "@controls": {
14     "self": {
15       "href": "http://localhost:9292/welcome/newest"
16     },

If my namespace maps to an object, is this better? It'd save me the repetition of a link relation including it.

17     "submissions:filter": {
18       "href": "http://localhost:9292/submission_filter_template/filter?category={category}&has_photo={has_photo}",
19       "isHrefTemplate": true,
20       "title": "filter submissions by category",
21       "description": "in addition to category, you can ensure the submission has a photo"
22     },
23     "submissions:add": {
24       "title": "add new submission",
25       "encoding": "json",
26       "href": "http://localhost:9292/submission_add_template/submit",
27       "method": "POST",
28       "template":
29       {
30         "title": "default title",
31         "category": "cats",
32         "photo_url": "http://cats.com"
33       }
34     }
35   }
36 }

[JornWildt]

"is:filter" gets expanded to "http://localhost:9292/rels#filter" right?

Yes.

the namespace, it's totally arbitrary, yes? "is" is just short for "issue"

Yes, mentally. Semantically it is short hand for "http://localhost:9292/rels#" using your namespace declaration. In my example it is sematically equivalent to something else. The "is" could as well have been "qw" or "bug" or another random short identifier.

Can I have more than one namespace?

I have not given it much attention, but that is the idea, yes.

If my namespace maps to an object, is this better?

Sorry, I do not know what you mean by "maps to an object".

Please be aware that using "localhost" for a link relation would be rather odd. Usually the link relation will refer to the organization behind the API. More like "http://info.acme.org/schema/rels/issue-tracker".

[mooreniemi]

Yeah for now, everything I'm generating is on localhost, so I can look at it as I go along. There's currently no settings to set the host url or anything, but there will be. :) Thanks again for your feedback and humoring all my questions!