{"action":"created","comment":{"url":"https://api.github.com/repos/refractproject/rfcs/pulls/comments/32820951","id":32820951,"diff_hunk":"@@ -0,0 +1,77 @@\n+- Start Date: 2015-06-18\n+- RFC PR: (leave this empty)\n+- Refract Issue: (leave this empty)\n+\n+# Summary\n+\n+Provide clarity and additional elements/properites in API Description namespace.\n+\n+# Motivation\n+\n+The purpose of this document is to make it easier for newcomers to understand the format and build tools around it.\n+\n+# Detailed design\n+\n+## Combine Namespaces\n+\n+We should combine the API Description namespace with the resource namespace.\n+Right now they are separate and it would be clearer if they were not.\n+\n+## Elements in Attributes\n+\n+Refract allows for including elements within the attributes section of an element.\n+Even though it’s possible, it may be helpful to avoid this in such an important namespace.\n+Reason being, this will be one of the first places people interact with Refract, and to use complex features may be too much.\n+\n+## HREF Variables\n+\n+We should call them “hrefVariables” everywhere instead of parameters in places (specifically transitions).\n+I think this will be more consistent and easier to understand for newcomers.\n+This will make more sense in how we handle inheritance as well, because parameters inheriting from hrefVariables does not seem optimal.\n+\n+## Defining Classes\n+\n+Swagger provides a way to define tags that can be applied to resources throughout the document.\n+Refract has the “class” attribute that we can use the same way, we only need a way to define a class name and provide the description for it.\n+Of course, this won’t carry over to API Blueprint, but that’s OK.\n+\f\n+## Clarify Inheritance\n+\n+We need to clarify how inheritance works by defining the behavior for:\n+\n+* HREF Variables and HREF values throughout the document\n+* Content types in payloads\n+* Methods in transitions\n+* Resources with schemas (though not in the spec) should be inherited by transitions\n+\n+## Transitions at Root\n+\n+We should be able to define transitions on the root of the document and not require they are nested within a resource.\n+This type of transition, though, should have a URL and a method.\n+\n+## Subclass Asset\n+\n+We should subclass the Asset Element and add one called “messageShema” and another called “messageBody.”\n+This will make reading a API Description make more sense than seeing Asset alone with classes.\n+\n+## Provided Media Types\n+\n+We should add a section that defines what media types the server will respond with.","path":"text/0000-clarity-api-description.md","position":59,"original_position":59,"commit_id":"39c0c9d9b715eb28945416476980c5d20a2e166e","original_commit_id":"39c0c9d9b715eb28945416476980c5d20a2e166e","user":{"login":"smizell","id":130959,"avatar_url":"https://avatars.githubusercontent.com/u/130959?v=3","gravatar_id":"","url":"https://api.github.com/users/smizell","html_url":"https://github.com/smizell","followers_url":"https://api.github.com/users/smizell/followers","following_url":"https://api.github.com/users/smizell/following{/other_user}","gists_url":"https://api.github.com/users/smizell/gists{/gist_id}","starred_url":"https://api.github.com/users/smizell/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/smizell/subscriptions","organizations_url":"https://api.github.com/users/smizell/orgs","repos_url":"https://api.github.com/users/smizell/repos","events_url":"https://api.github.com/users/smizell/events{/privacy}","received_events_url":"https://api.github.com/users/smizell/received_events","type":"User","site_admin":false},"body":"This is what the server MAY respond with. It is a list of hints at what the server provides, though the transactions may never show some of them.\r\n\r\nSwagger has a property called [produces](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object) that allows you to specify an array of available media types.\r\n\r\nIn reading over the Swagger spec again, I see that you can specify this `produces` on the API level. We do not have an API element to accommodate this, only `category`. This is a side question: should we have an `api` element for specifying this kind of API metadata?","created_at":"2015-06-19T11:27:35Z","updated_at":"2015-06-19T11:27:35Z","html_url":"https://github.com/refractproject/rfcs/pull/1#discussion_r32820951","pull_request_url":"https://api.github.com/repos/refractproject/rfcs/pulls/1","_links":{"self":{"href":"https://api.github.com/repos/refractproject/rfcs/pulls/comments/32820951"},"html":{"href":"https://github.com/refractproject/rfcs/pull/1#discussion_r32820951"},"pull_request":{"href":"https://api.github.com/repos/refractproject/rfcs/pulls/1"}}},"pull_request":{"url":"https://api.github.com/repos/refractproject/rfcs/pulls/1","id":38008730,"html_url":"https://github.com/refractproject/rfcs/pull/1","diff_url":"https://github.com/refractproject/rfcs/pull/1.diff","patch_url":"https://github.com/refractproject/rfcs/pull/1.patch","issue_url":"https://api.github.com/repos/refractproject/rfcs/issues/1","number":1,"state":"open","locked":false,"title":"Clarity for API Description namespace","user":{"login":"smizell","id":130959,"avatar_url":"https://avatars.githubusercontent.com/u/130959?v=3","gravatar_id":"","url":"https://api.github.com/users/smizell","html_url":"https://github.com/smizell","followers_url":"https://api.github.com/users/smizell/followers","following_url":"https://api.github.com/users/smizell/following{/other_user}","gists_url":"https://api.github.com/users/smizell/gists{/gist_id}","starred_url":"https://api.github.com/users/smizell/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/smizell/subscriptions","organizations_url":"https://api.github.com/users/smizell/orgs","repos_url":"https://api.github.com/users/smizell/repos","events_url":"https://api.github.com/users/smizell/events{/privacy}","received_events_url":"https://api.github.com/users/smizell/received_events","type":"User","site_admin":false},"body":"[Rendered](https://github.com/refractproject/rfcs/blob/smizell/clarity-api-description/text/0000-clarity-api-description.md)","created_at":"2015-06-18T13:53:29Z","updated_at":"2015-06-19T11:27:35Z","closed_at":null,"merged_at":null,"merge_commit_sha":"a788ecade3a61695a0927ac21b29aecbe4265e0f","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/refractproject/rfcs/pulls/1/commits","review_comments_url":"https://api.github.com/repos/refractproject/rfcs/pulls/1/comments","review_comment_url":"https://api.github.com/repos/refractproject/rfcs/pulls/comments{/number}","comments_url":"https://api.github.com/repos/refractproject/rfcs/issues/1/comments","statuses_url":"https://api.github.com/repos/refractproject/rfcs/statuses/39c0c9d9b715eb28945416476980c5d20a2e166e","head":{"label":"refractproject:smizell/clarity-api-description","ref":"smizell/clarity-api-description","sha":"39c0c9d9b715eb28945416476980c5d20a2e166e","user":{"login":"refractproject","id":10877387,"avatar_url":"https://avatars.githubusercontent.com/u/10877387?v=3","gravatar_id":"","url":"https://api.github.com/users/refractproject","html_url":"https://github.com/refractproject","followers_url":"https://api.github.com/users/refractproject/followers","following_url":"https://api.github.com/users/refractproject/following{/other_user}","gists_url":"https://api.github.com/users/refractproject/gists{/gist_id}","starred_url":"https://api.github.com/users/refractproject/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/refractproject/subscriptions","organizations_url":"https://api.github.com/users/refractproject/orgs","repos_url":"https://api.github.com/users/refractproject/repos","events_url":"https://api.github.com/users/refractproject/events{/privacy}","received_events_url":"https://api.github.com/users/refractproject/received_events","type":"Organization","site_admin":false},"repo":{"id":37661759,"name":"rfcs","full_name":"refractproject/rfcs","owner":{"login":"refractproject","id":10877387,"avatar_url":"https://avatars.githubusercontent.com/u/10877387?v=3","gravatar_id":"","url":"https://api.github.com/users/refractproject","html_url":"https://github.com/refractproject","followers_url":"https://api.github.com/users/refractproject/followers","following_url":"https://api.github.com/users/refractproject/following{/other_user}","gists_url":"https://api.github.com/users/refractproject/gists{/gist_id}","starred_url":"https://api.github.com/users/refractproject/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/refractproject/subscriptions","organizations_url":"https://api.github.com/users/refractproject/orgs","repos_url":"https://api.github.com/users/refractproject/repos","events_url":"https://api.github.com/users/refractproject/events{/privacy}","received_events_url":"https://api.github.com/users/refractproject/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/refractproject/rfcs","description":"RFCs for Changes to Refract and Refract Namespaces","fork":false,"url":"https://api.github.com/repos/refractproject/rfcs","forks_url":"https://api.github.com/repos/refractproject/rfcs/forks","keys_url":"https://api.github.com/repos/refractproject/rfcs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/refractproject/rfcs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/refractproject/rfcs/teams","hooks_url":"https://api.github.com/repos/refractproject/rfcs/hooks","issue_events_url":"https://api.github.com/repos/refractproject/rfcs/issues/events{/number}","events_url":"https://api.github.com/repos/refractproject/rfcs/events","assignees_url":"https://api.github.com/repos/refractproject/rfcs/assignees{/user}","branches_url":"https://api.github.com/repos/refractproject/rfcs/branches{/branch}","tags_url":"https://api.github.com/repos/refractproject/rfcs/tags","blobs_url":"https://api.github.com/repos/refractproject/rfcs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/refractproject/rfcs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/refractproject/rfcs/git/refs{/sha}","trees_url":"https://api.github.com/repos/refractproject/rfcs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/refractproject/rfcs/statuses/{sha}","languages_url":"https://api.github.com/repos/refractproject/rfcs/languages","stargazers_url":"https://api.github.com/repos/refractproject/rfcs/stargazers","contributors_url":"https://api.github.com/repos/refractproject/rfcs/contributors","subscribers_url":"https://api.github.com/repos/refractproject/rfcs/subscribers","subscription_url":"https://api.github.com/repos/refractproject/rfcs/subscription","commits_url":"https://api.github.com/repos/refractproject/rfcs/commits{/sha}","git_commits_url":"https://api.github.com/repos/refractproject/rfcs/git/commits{/sha}","comments_url":"https://api.github.com/repos/refractproject/rfcs/comments{/number}","issue_comment_url":"https://api.github.com/repos/refractproject/rfcs/issues/comments{/number}","contents_url":"https://api.github.com/repos/refractproject/rfcs/contents/{+path}","compare_url":"https://api.github.com/repos/refractproject/rfcs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/refractproject/rfcs/merges","archive_url":"https://api.github.com/repos/refractproject/rfcs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/refractproject/rfcs/downloads","issues_url":"https://api.github.com/repos/refractproject/rfcs/issues{/number}","pulls_url":"https://api.github.com/repos/refractproject/rfcs/pulls{/number}","milestones_url":"https://api.github.com/repos/refractproject/rfcs/milestones{/number}","notifications_url":"https://api.github.com/repos/refractproject/rfcs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/refractproject/rfcs/labels{/name}","releases_url":"https://api.github.com/repos/refractproject/rfcs/releases{/id}","created_at":"2015-06-18T13:41:44Z","updated_at":"2015-06-18T13:41:44Z","pushed_at":"2015-06-18T19:11:04Z","git_url":"git://github.com/refractproject/rfcs.git","ssh_url":"git@github.com:refractproject/rfcs.git","clone_url":"https://github.com/refractproject/rfcs.git","svn_url":"https://github.com/refractproject/rfcs","homepage":null,"size":0,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":1,"forks":0,"open_issues":1,"watchers":0,"default_branch":"master"}},"base":{"label":"refractproject:master","ref":"master","sha":"1f72b937e6880e6b816c7d8542e7ea96d2bbf0ed","user":{"login":"refractproject","id":10877387,"avatar_url":"https://avatars.githubusercontent.com/u/10877387?v=3","gravatar_id":"","url":"https://api.github.com/users/refractproject","html_url":"https://github.com/refractproject","followers_url":"https://api.github.com/users/refractproject/followers","following_url":"https://api.github.com/users/refractproject/following{/other_user}","gists_url":"https://api.github.com/users/refractproject/gists{/gist_id}","starred_url":"https://api.github.com/users/refractproject/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/refractproject/subscriptions","organizations_url":"https://api.github.com/users/refractproject/orgs","repos_url":"https://api.github.com/users/refractproject/repos","events_url":"https://api.github.com/users/refractproject/events{/privacy}","received_events_url":"https://api.github.com/users/refractproject/received_events","type":"Organization","site_admin":false},"repo":{"id":37661759,"name":"rfcs","full_name":"refractproject/rfcs","owner":{"login":"refractproject","id":10877387,"avatar_url":"https://avatars.githubusercontent.com/u/10877387?v=3","gravatar_id":"","url":"https://api.github.com/users/refractproject","html_url":"https://github.com/refractproject","followers_url":"https://api.github.com/users/refractproject/followers","following_url":"https://api.github.com/users/refractproject/following{/other_user}","gists_url":"https://api.github.com/users/refractproject/gists{/gist_id}","starred_url":"https://api.github.com/users/refractproject/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/refractproject/subscriptions","organizations_url":"https://api.github.com/users/refractproject/orgs","repos_url":"https://api.github.com/users/refractproject/repos","events_url":"https://api.github.com/users/refractproject/events{/privacy}","received_events_url":"https://api.github.com/users/refractproject/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/refractproject/rfcs","description":"RFCs for Changes to Refract and Refract Namespaces","fork":false,"url":"https://api.github.com/repos/refractproject/rfcs","forks_url":"https://api.github.com/repos/refractproject/rfcs/forks","keys_url":"https://api.github.com/repos/refractproject/rfcs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/refractproject/rfcs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/refractproject/rfcs/teams","hooks_url":"https://api.github.com/repos/refractproject/rfcs/hooks","issue_events_url":"https://api.github.com/repos/refractproject/rfcs/issues/events{/number}","events_url":"https://api.github.com/repos/refractproject/rfcs/events","assignees_url":"https://api.github.com/repos/refractproject/rfcs/assignees{/user}","branches_url":"https://api.github.com/repos/refractproject/rfcs/branches{/branch}","tags_url":"https://api.github.com/repos/refractproject/rfcs/tags","blobs_url":"https://api.github.com/repos/refractproject/rfcs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/refractproject/rfcs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/refractproject/rfcs/git/refs{/sha}","trees_url":"https://api.github.com/repos/refractproject/rfcs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/refractproject/rfcs/statuses/{sha}","languages_url":"https://api.github.com/repos/refractproject/rfcs/languages","stargazers_url":"https://api.github.com/repos/refractproject/rfcs/stargazers","contributors_url":"https://api.github.com/repos/refractproject/rfcs/contributors","subscribers_url":"https://api.github.com/repos/refractproject/rfcs/subscribers","subscription_url":"https://api.github.com/repos/refractproject/rfcs/subscription","commits_url":"https://api.github.com/repos/refractproject/rfcs/commits{/sha}","git_commits_url":"https://api.github.com/repos/refractproject/rfcs/git/commits{/sha}","comments_url":"https://api.github.com/repos/refractproject/rfcs/comments{/number}","issue_comment_url":"https://api.github.com/repos/refractproject/rfcs/issues/comments{/number}","contents_url":"https://api.github.com/repos/refractproject/rfcs/contents/{+path}","compare_url":"https://api.github.com/repos/refractproject/rfcs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/refractproject/rfcs/merges","archive_url":"https://api.github.com/repos/refractproject/rfcs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/refractproject/rfcs/downloads","issues_url":"https://api.github.com/repos/refractproject/rfcs/issues{/number}","pulls_url":"https://api.github.com/repos/refractproject/rfcs/pulls{/number}","milestones_url":"https://api.github.com/repos/refractproject/rfcs/milestones{/number}","notifications_url":"https://api.github.com/repos/refractproject/rfcs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/refractproject/rfcs/labels{/name}","releases_url":"https://api.github.com/repos/refractproject/rfcs/releases{/id}","created_at":"2015-06-18T13:41:44Z","updated_at":"2015-06-18T13:41:44Z","pushed_at":"2015-06-18T19:11:04Z","git_url":"git://github.com/refractproject/rfcs.git","ssh_url":"git@github.com:refractproject/rfcs.git","clone_url":"https://github.com/refractproject/rfcs.git","svn_url":"https://github.com/refractproject/rfcs","homepage":null,"size":0,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":1,"forks":0,"open_issues":1,"watchers":0,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/refractproject/rfcs/pulls/1"},"html":{"href":"https://github.com/refractproject/rfcs/pull/1"},"issue":{"href":"https://api.github.com/repos/refractproject/rfcs/issues/1"},"comments":{"href":"https://api.github.com/repos/refractproject/rfcs/issues/1/comments"},"review_comments":{"href":"https://api.github.com/repos/refractproject/rfcs/pulls/1/comments"},"review_comment":{"href":"https://api.github.com/repos/refractproject/rfcs/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/refractproject/rfcs/pulls/1/commits"},"statuses":{"href":"https://api.github.com/repos/refractproject/rfcs/statuses/39c0c9d9b715eb28945416476980c5d20a2e166e"}}}}