Web Linking, Profiles etc
Jack Whelpton
Jørn Wildt
--
You received this message because you are subscribed to the Google Groups "Mason media type" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mason-media-type+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Jørn Wildt
--
Jack Whelpton
Hi Jørn,
Thanks for the reply, sorry it’s taken me a couple of weeks to get back… you know how the day job can be sometimes! As a little background on the project in hand, I’m working on the API layer for a catalog system. This is a problem I’ve tackled before, often taking a slightly different tack each time; previously I’d been worked with a custom media type, but this time around I was keen to standardize a little. The integrations are initially a little unclear, but I’ve tended to use the catalog maintenance UI as a good proving ground for the API design; one of the first integrations that you can envisage is an internal editing tool. I’m not, however, trying to burden the API with presentation concerns.
Even within such a limited use case, I’ve found hypermedia affordances handy: for example, the API can provide links from “search results” to details of an individual product etc.
That briefest of explanations does at least provide enough for me to leap into your questions:
1) Mason has no language support. You need to encode that yourself somehow. Can you give a more detailed example of how you would use it?
Multi-lingual support is pretty subtle. We maintain individual “translations” of product information, which can be updated independently. The Accept-Language header isn’t designed for targeting different resources for updating etc., so these translations get their own URIs, something like:
/product/{id}/language/{language}
e.g.:
/product/1/language/en-us
The Accept-Language header is used to determine the language of metadata: names of product attributes, the name of the product’s category/type/genre etc.
I can see a use for exposing a list of all the translations available for a product, via a URI something like:
/product/1/languages
Previously I’ve returned this as a list of links of a custom type, with a different hreflang. I’m guessing something like:
{
"@namespaces": { "cat": { "name": "http://rels.example.org/" } },
"@controls": {
"cat:product": {
"href": "/product/1/language/en",
"hreflang": "en",
"alt": [
{ "href": "/product/1/language/fr", "hreflang": "fr" },
{ "href": "/product/1/language/ja", "hreflang": "ja" },
{ "href": "/product/1/language/en-us", "hreflang": "en-us" }
]
}
}
}
One alternative approach would be to create minimal product representations, bearing the language property and a canonical link, something like:
{
"@namespaces": { "cat": { "name": "http://rels.example.org/" } },
"translations": [
{
"@controls": { "canonical": "/product/1/language/fr" },
"language": "fr"
},
{
"@controls": { "canonical": "/product/1/language/ja" },
"language": "ja"
},
{
"@controls": { "canonical": "/product/1/language/en-us" },
"language": "en-us"
}
]
}
2) You are right about the use of "alt" in links. And, yes, I understand that none of the "related" links are supposed to be more primary than the others. Think of it as a list instead with the primary simply being the first in the list.
Cool, I just wanted to check that wasn’t a perversion of the spec. The example above shows this in action.
3) Profiles are not supported. It could make sense to add it. You can always just add your own JSON property value named "MyProfileIndicator" (or what ever else) and tell your client devs how to understand it.
I was always planning on doing this: it doesn’t need a custom JSON property, as the “profile” link relation is defined in the IANA link registry. Here’s how I’ve used it before:
{
"@controls": {
"profile": {
"href": "http://profiles.example.org?resource=product&name=canonical&version=1",
}
}
}
I can thus use this to handle versioning when absolutely required, on a per-resource basis, and I can offer lighter-weight payloads (e.g. name=”search-result”). The URI provides me somewhere to hang documentation for the client developer, usually just human-readable text.
However, for this to work for versioning I really want to support a client sending a request for a specific profile, thus:
Accept: application/vnd.mason+json;profile=http://profiles.example.org?version=1
The book I’m currently reading suggests, as a workaround for media types that don’t support this,
Link: <http://profiles.example.org?version=1>; rel=profile
But this seems clunkier/less expressive to me.
Interesting that you mention multiple inheritance; I’ve done something similar before, but not exactly using profiles. I provided documentation that said the IANA link relation “collection” would always return results that adhere to the “page” profile, and I’d have links like:
{
"@namespaces": { "cat": { "name": "http://rels.example.org/" } },
"@controls": {
"cat:product collection": {
"href": "/product/1/languages"
}
}
}
I don’t know if there’s a way to do this in Mason… create a single link with multiple types?
This might be an argument for the Link approach above, as you could easily specify multiple profiles:
Link: <http://profiles.example.org?resource=product&version=1>; rel=profile
Link: <http://profiles.example.org?resource=page>; rel=profile
Incidentally, on the subject of pagination properties, is the @meta block the best place for these (currentPage, pageCount, pageSize, totalCount)? I’m guessing so.
I think that’s most of my musings for now… sorry for the mass of verbiage, but this is an interesting area and will help me understand how best to leverage Mason (or, indeed, if something else would be more appropriate).
Cheers,
Jack.
--
To unsubscribe from this group and stop receiving emails from it, send an email to mason-media-ty...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups "Mason media type" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mason-media-ty...@googlegroups.com.