{"action":"created","issue":{"url":"https://api.github.com/repos/restful-api-description-language/RADL/issues/16","labels_url":"https://api.github.com/repos/restful-api-description-language/RADL/issues/16/labels{/name}","comments_url":"https://api.github.com/repos/restful-api-description-language/RADL/issues/16/comments","events_url":"https://api.github.com/repos/restful-api-description-language/RADL/issues/16/events","html_url":"https://github.com/restful-api-description-language/RADL/issues/16","id":68635964,"number":16,"title":"Indicating scope for link relations (e.g. for feeds)","user":{"login":"jonathanrobie","id":1767869,"avatar_url":"https://avatars.githubusercontent.com/u/1767869?v=3","gravatar_id":"","url":"https://api.github.com/users/jonathanrobie","html_url":"https://github.com/jonathanrobie","followers_url":"https://api.github.com/users/jonathanrobie/followers","following_url":"https://api.github.com/users/jonathanrobie/following{/other_user}","gists_url":"https://api.github.com/users/jonathanrobie/gists{/gist_id}","starred_url":"https://api.github.com/users/jonathanrobie/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jonathanrobie/subscriptions","organizations_url":"https://api.github.com/users/jonathanrobie/orgs","repos_url":"https://api.github.com/users/jonathanrobie/repos","events_url":"https://api.github.com/users/jonathanrobie/events{/privacy}","received_events_url":"https://api.github.com/users/jonathanrobie/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":4,"created_at":"2015-04-15T10:07:32Z","updated_at":"2015-04-16T12:11:15Z","closed_at":null,"body":"For some representations, the meaning of a link relation depends on where it occurs in the representation.  For example, in the following example from the Atom specification, the 'alternate' link relation is used (1) in the feed itself, and (2) in an entry contained in the feed.  The scope of the link relation depends on where it is found.  How should we handle this case?\r\n\r\nSome possibilities:\r\n\r\n- We could add a scope attribute, e.g. <link-relation name=\"edit\" scope=\"entry\">\r\n- We could use naming conventions, e.g. 'alternate' vs. 'alternate (in entry)'.\r\n- We could ask the designer to state the scope in documentation.\r\n\r\n```\r\n   <?xml version=\"1.0\" encoding=\"utf-8\"?>\r\n   <feed xmlns=\"http://www.w3.org/2005/Atom\">\r\n     <title type=\"text\">dive into mark</title>\r\n     <subtitle type=\"html\">\r\n       A &lt;em&gt;lot&lt;/em&gt; of effort\r\n       went into making this effortless\r\n     </subtitle>\r\n     <updated>2005-07-31T12:29:29Z</updated>\r\n     <id>tag:example.org,2003:3</id>\r\n     <link rel=\"alternate\" type=\"text/html\"\r\n      hreflang=\"en\" href=\"http://example.org/\"/>\r\n     <link rel=\"self\" type=\"application/atom+xml\"\r\n      href=\"http://example.org/feed.atom\"/>\r\n     <rights>Copyright (c) 2003, Mark Pilgrim</rights>\r\n     <generator uri=\"http://www.example.com/\" version=\"1.0\">\r\n       Example Toolkit\r\n     </generator>\r\n     <entry>\r\n       <title>Atom draft-07 snapshot</title>\r\n       <link rel=\"alternate\" type=\"text/html\"\r\n        href=\"http://example.org/2005/04/02/atom\"/>\r\n       <link rel=\"enclosure\" type=\"audio/mpeg\" length=\"1337\"\r\n        href=\"http://example.org/audio/ph34r_my_podcast.mp3\"/>\r\n       <id>tag:example.org,2003:3.2397</id>\r\n       <updated>2005-07-31T12:29:29Z</updated>\r\n       <published>2003-12-13T08:29:29-04:00</published>\r\n       <author>\r\n         <name>Mark Pilgrim</name>\r\n         <uri>http://example.org/</uri>\r\n         <email>f8dy@example.com</email>\r\n       </author>\r\n       <contributor>\r\n         <name>Sam Ruby</name>\r\n       </contributor>\r\n       <contributor>\r\n         <name>Joe Gregorio</name>\r\n       </contributor>\r\n       <content type=\"xhtml\" xml:lang=\"en\"\r\n        xml:base=\"http://diveintomark.org/\">\r\n         <div xmlns=\"http://www.w3.org/1999/xhtml\">\r\n           <p><i>[Update: The Atom draft is finished.]</i></p>\r\n         </div>\r\n       </content>\r\n     </entry>\r\n   </feed>```"},"comment":{"url":"https://api.github.com/repos/restful-api-description-language/RADL/issues/comments/93718823","html_url":"https://github.com/restful-api-description-language/RADL/issues/16#issuecomment-93718823","issue_url":"https://api.github.com/repos/restful-api-description-language/RADL/issues/16","id":93718823,"user":{"login":"ApiSecRay","id":3496035,"avatar_url":"https://avatars.githubusercontent.com/u/3496035?v=3","gravatar_id":"","url":"https://api.github.com/users/ApiSecRay","html_url":"https://github.com/ApiSecRay","followers_url":"https://api.github.com/users/ApiSecRay/followers","following_url":"https://api.github.com/users/ApiSecRay/following{/other_user}","gists_url":"https://api.github.com/users/ApiSecRay/gists{/gist_id}","starred_url":"https://api.github.com/users/ApiSecRay/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ApiSecRay/subscriptions","organizations_url":"https://api.github.com/users/ApiSecRay/orgs","repos_url":"https://api.github.com/users/ApiSecRay/repos","events_url":"https://api.github.com/users/ApiSecRay/events{/privacy}","received_events_url":"https://api.github.com/users/ApiSecRay/received_events","type":"User","site_admin":false},"created_at":"2015-04-16T12:11:15Z","updated_at":"2015-04-16T12:11:15Z","body":"There is only a problem if *in a single response*, there are multiple links typed by the same link relation and those links are in different scopes. I have never seen that, so I don't know if this is a problem worth solving and if it is, worth spending extra markup on.\r\n\r\nI think the presented example is contrived, because an HTML version of a collection would not be very valuable in an API, i.e. in a scenario where a program rather than a human consumes the response. I'm having trouble envisioning a realistic scenario where a REST client would retrieve an Atom feed and then follow the `alternate` link on the feed level to get the same information in a different format.\r\n\r\nMaybe that's just my limited imagination :wink:. Feel free to open my eyes."}}