{"action":"created","issue":{"url":"https://api.github.com/repos/JornWildt/Mason/issues/2","labels_url":"https://api.github.com/repos/JornWildt/Mason/issues/2/labels{/name}","comments_url":"https://api.github.com/repos/JornWildt/Mason/issues/2/comments","events_url":"https://api.github.com/repos/JornWildt/Mason/issues/2/events","html_url":"https://github.com/JornWildt/Mason/issues/2","id":26509641,"number":2,"title":"Discussion: is the \"alt\" property on links a good solution?","user":{"login":"JornWildt","id":274072,"avatar_url":"https://avatars.githubusercontent.com/u/274072?v=3","gravatar_id":"","url":"https://api.github.com/users/JornWildt","html_url":"https://github.com/JornWildt","followers_url":"https://api.github.com/users/JornWildt/followers","following_url":"https://api.github.com/users/JornWildt/following{/other_user}","gists_url":"https://api.github.com/users/JornWildt/gists{/gist_id}","starred_url":"https://api.github.com/users/JornWildt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/JornWildt/subscriptions","organizations_url":"https://api.github.com/users/JornWildt/orgs","repos_url":"https://api.github.com/users/JornWildt/repos","events_url":"https://api.github.com/users/JornWildt/events{/privacy}","received_events_url":"https://api.github.com/users/JornWildt/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/JornWildt/Mason/labels/question","name":"question","color":"cc317c"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":16,"created_at":"2014-01-29T10:10:38Z","updated_at":"2015-03-25T21:25:16Z","closed_at":null,"body":"A link in Mason is always represented as a single object. If there are more links for the same link relation type (property name in the @links object) then they will be added as an array of link objects in the \"alt\" property:\r\n\r\n```json\r\n\"@links\": {\r\n  // Primary link for \"contact\"\r\n  \"contact\": {\r\n    \"href\": \"...\",\r\n    \"title\": \"Contact information\",\r\n    \"type\": \"application/vnd.mason+json\",\r\n\r\n    // Alternate links for \"contact\"\r\n    \"alt\": [\r\n      {\r\n        href: \"...\",\r\n        \"title\": \"Contact information (in vCard)\",\r\n        \"type\": \"text/vcard\"\r\n      }\r\n    ]\r\n  }\r\n}\r\n```\r\n\r\n**Is this a good solution?**\r\n"},"comment":{"url":"https://api.github.com/repos/JornWildt/Mason/issues/comments/86223245","html_url":"https://github.com/JornWildt/Mason/issues/2#issuecomment-86223245","issue_url":"https://api.github.com/repos/JornWildt/Mason/issues/2","id":86223245,"user":{"login":"JornWildt","id":274072,"avatar_url":"https://avatars.githubusercontent.com/u/274072?v=3","gravatar_id":"","url":"https://api.github.com/users/JornWildt","html_url":"https://github.com/JornWildt","followers_url":"https://api.github.com/users/JornWildt/followers","following_url":"https://api.github.com/users/JornWildt/following{/other_user}","gists_url":"https://api.github.com/users/JornWildt/gists{/gist_id}","starred_url":"https://api.github.com/users/JornWildt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/JornWildt/subscriptions","organizations_url":"https://api.github.com/users/JornWildt/orgs","repos_url":"https://api.github.com/users/JornWildt/repos","events_url":"https://api.github.com/users/JornWildt/events{/privacy}","received_events_url":"https://api.github.com/users/JornWildt/received_events","type":"User","site_admin":false},"created_at":"2015-03-25T21:25:16Z","updated_at":"2015-03-25T21:25:16Z","body":"Warning: ramblings ahead ...\r\n\r\n> \"Alt\" sounds like content type differences - jpg, png, gif or json, json+hal, json+mason\r\n\r\nYes, it boils down to me having a specific, maybe wrong, understanding of multiple links of the same rel-type. I believe it comes from the ATOM link spec, but I cannot find it again, so I may easily be wrong. I remember it as saying \"if there are multiple links of the same rel-type then they must differ on the expected media type\" - strongly indicating that multiple links means different media types.\r\n\r\nThen, from the HAL discussion on this issue, I realized that there may be other reasons for having multiple links of the same link-rel. For instance links to multiple stylesheets as used in HTML. This has now made me question the idea of using the \"alt\" approach.\r\n\r\nWhat this means is that we have different ways of interpreting links of the same rel-type: it can be links to alternate representations of the same resource or it can be links to multiple different resources.\r\n\r\nI am not a big fan of links to multiple resources because it can be represented as a plain JSON array of items with \"self\" links to the individual resources. But I do recognize that it may be useful in some simple scenarios.\r\n\r\nHere is how I would encode multiple links to different resources - using as example a collection of items:\r\n\r\n```\r\n{\r\n  items:\r\n  [\r\n    {\r\n      id: 1234,\r\n      title: \"Item A\",\r\n      weight: 15,\r\n      @controls:\r\n      {\r\n        self: { href: \"http://api.com/items/1234\" }\r\n      }\r\n    },\r\n    {\r\n      id: 4321,\r\n      title: \"Item B\",\r\n      weight: 22,\r\n      @controls:\r\n      {\r\n        self: { href: \"http://api.com/items/4321\" }\r\n      }\r\n    }\r\n  ]\r\n}\r\n```\r\nUsing arrays like this allows the server to embed all sorts of partial data from the linked resource without trying to cram it into the @controls items.\r\n\r\nPlease be aware that this is different from HAL which would expect you to use _embedded for this purpose.\r\n\r\nFor the above reasons it may just be that the \"alt\" approach is valid - but obviously not what people are expecting which certainly is a problem :-)\r\n\r\n\r\n> Imagine, just as an example, that you had both @link (for singleton/objects) and @links for zero or more\r\n\r\nThat won't be a viable way as Mason v2 unifies links, link templates and actions in a single @controls object. See https://github.com/JornWildt/Mason/blob/master/Documentation/Mason-draft-2.md#property-name-controls.\r\n\r\n\r\n> On the other hand, giving up simple dot dereferencing for the common case seems misguided. The prime example would be self where you know there is exactly one. I guess in HAL it's zero or one.\r\n\r\n> Can you think of an example where self would have alts?\r\n\r\nNo, but I have a similar example - the \"author\" rel-type. It identifies links to the author of the page (see http://www.w3.org/TR/html5/links.html#link-type-author). You may start out with a single \"author\" link because you only have a single author representation. But later on you figure out that you have both Mason, vCard, jCard and xCard representations - and that works very well with \"alt\" approach as these can simply be added as links to alternate representations without breaking clients that only depends on the primary link.\r\n\r\nSo - if one insists on multiple links of the same link-rel means variations of the same resource (like I tend to, but I'm still not sure) then \"alt\" seems pretty good. If you are in the other camp where multiple links can refer to different resources then, well, \"alt\" is not perfect - but, as shown above, you can \r\n\r\n> But to your main point about \"one day we woke up...\" scenario. Fundamentally, what this means is that the API changed and a given relation is no longer a singleton. The key here, to me, is the API changed. \r\n\r\nUnless we simply added links to different representations of the same resource (as \"alt\" links).\r\n\r\nBut I also agree with you. If the API, as an example, goes from using one single address for a customer to having many addresses for a customer then it would be a breaking change.\r\n\r\n> I'm with you on the client library.\r\n\r\nSo am I.\r\n\r\nI am working on one for C# with Ramone (which already has rudimentary support for selecting links and following them as well as invoking key/value forms from HTML). See https://github.com/JornWildt/Ramone.\r\n\r\n> This is partly why I asked recently in the HAL discussion group if there was a standard client model\r\n\r\nI also believe there should be a standard client model/processing-rules and started work on that in Mason v2 (see https://github.com/JornWildt/Mason/blob/master/Documentation/Mason-draft-2.md#client-processing-rules).\r\n\r\nI should add something on how to handle null/empty-list/singular/plural links ... when we have straighten out what it means :-)\r\n\r\n\r\n*** CONCLUSION ***\r\n\r\nRight now I am leaning towards the existing \"alt\" approach where \"alt\" means alternate links to the same resource represented in different ways. In this world the server should represent links to multiple resources (a collection of items) as a plain JSON array with multiple \"self\" links:\r\n\r\n```\r\n{\r\n  items:\r\n  [\r\n    {\r\n      id: 1234,\r\n      title: \"Item A\",\r\n      weight: 15,\r\n      @controls:\r\n      {\r\n        self: { href: \"http://api.com/items/1234\" }\r\n      }\r\n    },\r\n    {\r\n      id: 4321,\r\n      title: \"Item B\",\r\n      weight: 22,\r\n      @controls:\r\n      {\r\n        self: { href: \"http://api.com/items/4321\" }\r\n      }\r\n    }\r\n  ]\r\n}\r\n```"}}