{"action":"created","comment":{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/comments/24703510","id":24703510,"diff_hunk":"@@ -127,6 +164,8 @@ Kubernetes by convention exposes additional verbs as new endpoints with singular\n \n Support of additional verbs is not required for all object types.\n \n+When resources wish to expose alternative actions, they should do so using new sub-resources or as new top level resources. An example is allowing automated processes to update the \"status\" field of a Pod. The `/pods` endpoint only allows updates to \"metadata\" and \"spec\", since those reflect user intent. An automated process should be able to modify status for users to see by sending an updated Pod kind to the server to the \"/pods/&lt;name&gt;/status\" endpoint - the alternate endpoint allows different rules to be applied to the update, and access to be appropriately restricted.","path":"docs/api-conventions.md","position":149,"original_position":149,"commit_id":"98da984f3fa15e1da57d3f389cc35227fb28b533","original_commit_id":"98da984f3fa15e1da57d3f389cc35227fb28b533","user":{"login":"bgrant0607","id":7725777,"avatar_url":"https://avatars.githubusercontent.com/u/7725777?v=3","gravatar_id":"","url":"https://api.github.com/users/bgrant0607","html_url":"https://github.com/bgrant0607","followers_url":"https://api.github.com/users/bgrant0607/followers","following_url":"https://api.github.com/users/bgrant0607/following{/other_user}","gists_url":"https://api.github.com/users/bgrant0607/gists{/gist_id}","starred_url":"https://api.github.com/users/bgrant0607/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bgrant0607/subscriptions","organizations_url":"https://api.github.com/users/bgrant0607/orgs","repos_url":"https://api.github.com/users/bgrant0607/repos","events_url":"https://api.github.com/users/bgrant0607/events{/privacy}","received_events_url":"https://api.github.com/users/bgrant0607/received_events","type":"User","site_admin":false},"body":"I feel we need some guidance about when each might be appropriate.\r\n\r\nIMO, /proxy and /redirect aren't really API calls. They are apiserver services.\r\n\r\n/watch is sort of like a custom HTTP verb. It doesn't change the resources returned. \r\n\r\nWhat all these prefix-based paths have in common is that they are transport-oriented.\r\n\r\nI prefer the more object-oriented subresource approach for the cases discussed in this PR: binding, status, size, stop, restart, clone, suspend, etc.","created_at":"2015-02-13T22:43:46Z","updated_at":"2015-02-13T22:43:46Z","html_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/4375#discussion_r24703510","pull_request_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/4375","_links":{"self":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/comments/24703510"},"html":{"href":"https://github.com/GoogleCloudPlatform/kubernetes/pull/4375#discussion_r24703510"},"pull_request":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/4375"}}},"pull_request":{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/4375","id":29155010,"html_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/4375","diff_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/4375.diff","patch_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/4375.patch","issue_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/4375","number":4375,"state":"open","locked":false,"title":"Clarify the difference between kinds and resources in the API","user":{"login":"smarterclayton","id":1163175,"avatar_url":"https://avatars.githubusercontent.com/u/1163175?v=3","gravatar_id":"","url":"https://api.github.com/users/smarterclayton","html_url":"https://github.com/smarterclayton","followers_url":"https://api.github.com/users/smarterclayton/followers","following_url":"https://api.github.com/users/smarterclayton/following{/other_user}","gists_url":"https://api.github.com/users/smarterclayton/gists{/gist_id}","starred_url":"https://api.github.com/users/smarterclayton/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/smarterclayton/subscriptions","organizations_url":"https://api.github.com/users/smarterclayton/orgs","repos_url":"https://api.github.com/users/smarterclayton/repos","events_url":"https://api.github.com/users/smarterclayton/events{/privacy}","received_events_url":"https://api.github.com/users/smarterclayton/received_events","type":"User","site_admin":false},"body":"As we prepare to expose additional endpoints for pod status, cloning,\nbinding, and templating, we should clarify the terminology and\ndistinctions. Use pod status as an example of an alternative \"resource\"\nthat shares the same \"kind\" (schema) as pods.\n\n@bgrant0607","created_at":"2015-02-12T06:04:24Z","updated_at":"2015-02-13T22:43:46Z","closed_at":null,"merged_at":null,"merge_commit_sha":"31fbdce607afc788b683e96e4d3261dad2f3f8dc","assignee":{"login":"bgrant0607","id":7725777,"avatar_url":"https://avatars.githubusercontent.com/u/7725777?v=3","gravatar_id":"","url":"https://api.github.com/users/bgrant0607","html_url":"https://github.com/bgrant0607","followers_url":"https://api.github.com/users/bgrant0607/followers","following_url":"https://api.github.com/users/bgrant0607/following{/other_user}","gists_url":"https://api.github.com/users/bgrant0607/gists{/gist_id}","starred_url":"https://api.github.com/users/bgrant0607/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bgrant0607/subscriptions","organizations_url":"https://api.github.com/users/bgrant0607/orgs","repos_url":"https://api.github.com/users/bgrant0607/repos","events_url":"https://api.github.com/users/bgrant0607/events{/privacy}","received_events_url":"https://api.github.com/users/bgrant0607/received_events","type":"User","site_admin":false},"milestone":null,"commits_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/4375/commits","review_comments_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/4375/comments","review_comment_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/comments/{number}","comments_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/4375/comments","statuses_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/statuses/98da984f3fa15e1da57d3f389cc35227fb28b533","head":{"label":"smarterclayton:clarify_resources_and_kinds","ref":"clarify_resources_and_kinds","sha":"98da984f3fa15e1da57d3f389cc35227fb28b533","user":{"login":"smarterclayton","id":1163175,"avatar_url":"https://avatars.githubusercontent.com/u/1163175?v=3","gravatar_id":"","url":"https://api.github.com/users/smarterclayton","html_url":"https://github.com/smarterclayton","followers_url":"https://api.github.com/users/smarterclayton/followers","following_url":"https://api.github.com/users/smarterclayton/following{/other_user}","gists_url":"https://api.github.com/users/smarterclayton/gists{/gist_id}","starred_url":"https://api.github.com/users/smarterclayton/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/smarterclayton/subscriptions","organizations_url":"https://api.github.com/users/smarterclayton/orgs","repos_url":"https://api.github.com/users/smarterclayton/repos","events_url":"https://api.github.com/users/smarterclayton/events{/privacy}","received_events_url":"https://api.github.com/users/smarterclayton/received_events","type":"User","site_admin":false},"repo":{"id":21225407,"name":"kubernetes","full_name":"smarterclayton/kubernetes","owner":{"login":"smarterclayton","id":1163175,"avatar_url":"https://avatars.githubusercontent.com/u/1163175?v=3","gravatar_id":"","url":"https://api.github.com/users/smarterclayton","html_url":"https://github.com/smarterclayton","followers_url":"https://api.github.com/users/smarterclayton/followers","following_url":"https://api.github.com/users/smarterclayton/following{/other_user}","gists_url":"https://api.github.com/users/smarterclayton/gists{/gist_id}","starred_url":"https://api.github.com/users/smarterclayton/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/smarterclayton/subscriptions","organizations_url":"https://api.github.com/users/smarterclayton/orgs","repos_url":"https://api.github.com/users/smarterclayton/repos","events_url":"https://api.github.com/users/smarterclayton/events{/privacy}","received_events_url":"https://api.github.com/users/smarterclayton/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/smarterclayton/kubernetes","description":"Container Cluster Manager","fork":true,"url":"https://api.github.com/repos/smarterclayton/kubernetes","forks_url":"https://api.github.com/repos/smarterclayton/kubernetes/forks","keys_url":"https://api.github.com/repos/smarterclayton/kubernetes/keys{/key_id}","collaborators_url":"https://api.github.com/repos/smarterclayton/kubernetes/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/smarterclayton/kubernetes/teams","hooks_url":"https://api.github.com/repos/smarterclayton/kubernetes/hooks","issue_events_url":"https://api.github.com/repos/smarterclayton/kubernetes/issues/events{/number}","events_url":"https://api.github.com/repos/smarterclayton/kubernetes/events","assignees_url":"https://api.github.com/repos/smarterclayton/kubernetes/assignees{/user}","branches_url":"https://api.github.com/repos/smarterclayton/kubernetes/branches{/branch}","tags_url":"https://api.github.com/repos/smarterclayton/kubernetes/tags","blobs_url":"https://api.github.com/repos/smarterclayton/kubernetes/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/smarterclayton/kubernetes/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/smarterclayton/kubernetes/git/refs{/sha}","trees_url":"https://api.github.com/repos/smarterclayton/kubernetes/git/trees{/sha}","statuses_url":"https://api.github.com/repos/smarterclayton/kubernetes/statuses/{sha}","languages_url":"https://api.github.com/repos/smarterclayton/kubernetes/languages","stargazers_url":"https://api.github.com/repos/smarterclayton/kubernetes/stargazers","contributors_url":"https://api.github.com/repos/smarterclayton/kubernetes/contributors","subscribers_url":"https://api.github.com/repos/smarterclayton/kubernetes/subscribers","subscription_url":"https://api.github.com/repos/smarterclayton/kubernetes/subscription","commits_url":"https://api.github.com/repos/smarterclayton/kubernetes/commits{/sha}","git_commits_url":"https://api.github.com/repos/smarterclayton/kubernetes/git/commits{/sha}","comments_url":"https://api.github.com/repos/smarterclayton/kubernetes/comments{/number}","issue_comment_url":"https://api.github.com/repos/smarterclayton/kubernetes/issues/comments/{number}","contents_url":"https://api.github.com/repos/smarterclayton/kubernetes/contents/{+path}","compare_url":"https://api.github.com/repos/smarterclayton/kubernetes/compare/{base}...{head}","merges_url":"https://api.github.com/repos/smarterclayton/kubernetes/merges","archive_url":"https://api.github.com/repos/smarterclayton/kubernetes/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/smarterclayton/kubernetes/downloads","issues_url":"https://api.github.com/repos/smarterclayton/kubernetes/issues{/number}","pulls_url":"https://api.github.com/repos/smarterclayton/kubernetes/pulls{/number}","milestones_url":"https://api.github.com/repos/smarterclayton/kubernetes/milestones{/number}","notifications_url":"https://api.github.com/repos/smarterclayton/kubernetes/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/smarterclayton/kubernetes/labels{/name}","releases_url":"https://api.github.com/repos/smarterclayton/kubernetes/releases{/id}","created_at":"2014-06-26T02:28:13Z","updated_at":"2014-06-26T01:04:38Z","pushed_at":"2015-02-13T18:46:01Z","git_url":"git://github.com/smarterclayton/kubernetes.git","ssh_url":"git@github.com:smarterclayton/kubernetes.git","clone_url":"https://github.com/smarterclayton/kubernetes.git","svn_url":"https://github.com/smarterclayton/kubernetes","homepage":null,"size":30478,"stargazers_count":0,"watchers_count":0,"language":"Go","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1,"mirror_url":null,"open_issues_count":2,"forks":1,"open_issues":2,"watchers":0,"default_branch":"master"}},"base":{"label":"GoogleCloudPlatform:master","ref":"master","sha":"7d4397161448ea8bf9ce62b228f875d550e05393","user":{"login":"GoogleCloudPlatform","id":2810941,"avatar_url":"https://avatars.githubusercontent.com/u/2810941?v=3","gravatar_id":"","url":"https://api.github.com/users/GoogleCloudPlatform","html_url":"https://github.com/GoogleCloudPlatform","followers_url":"https://api.github.com/users/GoogleCloudPlatform/followers","following_url":"https://api.github.com/users/GoogleCloudPlatform/following{/other_user}","gists_url":"https://api.github.com/users/GoogleCloudPlatform/gists{/gist_id}","starred_url":"https://api.github.com/users/GoogleCloudPlatform/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/GoogleCloudPlatform/subscriptions","organizations_url":"https://api.github.com/users/GoogleCloudPlatform/orgs","repos_url":"https://api.github.com/users/GoogleCloudPlatform/repos","events_url":"https://api.github.com/users/GoogleCloudPlatform/events{/privacy}","received_events_url":"https://api.github.com/users/GoogleCloudPlatform/received_events","type":"Organization","site_admin":false},"repo":{"id":20580498,"name":"kubernetes","full_name":"GoogleCloudPlatform/kubernetes","owner":{"login":"GoogleCloudPlatform","id":2810941,"avatar_url":"https://avatars.githubusercontent.com/u/2810941?v=3","gravatar_id":"","url":"https://api.github.com/users/GoogleCloudPlatform","html_url":"https://github.com/GoogleCloudPlatform","followers_url":"https://api.github.com/users/GoogleCloudPlatform/followers","following_url":"https://api.github.com/users/GoogleCloudPlatform/following{/other_user}","gists_url":"https://api.github.com/users/GoogleCloudPlatform/gists{/gist_id}","starred_url":"https://api.github.com/users/GoogleCloudPlatform/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/GoogleCloudPlatform/subscriptions","organizations_url":"https://api.github.com/users/GoogleCloudPlatform/orgs","repos_url":"https://api.github.com/users/GoogleCloudPlatform/repos","events_url":"https://api.github.com/users/GoogleCloudPlatform/events{/privacy}","received_events_url":"https://api.github.com/users/GoogleCloudPlatform/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/GoogleCloudPlatform/kubernetes","description":"Container Cluster Manager","fork":false,"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes","forks_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/forks","keys_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/keys{/key_id}","collaborators_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/teams","hooks_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/hooks","issue_events_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/events{/number}","events_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/events","assignees_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/assignees{/user}","branches_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/branches{/branch}","tags_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/tags","blobs_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/git/refs{/sha}","trees_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/git/trees{/sha}","statuses_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/statuses/{sha}","languages_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/languages","stargazers_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/stargazers","contributors_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/contributors","subscribers_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/subscribers","subscription_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/subscription","commits_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/commits{/sha}","git_commits_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/git/commits{/sha}","comments_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/comments{/number}","issue_comment_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/comments/{number}","contents_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/contents/{+path}","compare_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/compare/{base}...{head}","merges_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/merges","archive_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/downloads","issues_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues{/number}","pulls_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls{/number}","milestones_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/milestones{/number}","notifications_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/labels{/name}","releases_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/releases{/id}","created_at":"2014-06-06T22:56:04Z","updated_at":"2015-02-13T22:31:48Z","pushed_at":"2015-02-13T22:31:48Z","git_url":"git://github.com/GoogleCloudPlatform/kubernetes.git","ssh_url":"git@github.com:GoogleCloudPlatform/kubernetes.git","clone_url":"https://github.com/GoogleCloudPlatform/kubernetes.git","svn_url":"https://github.com/GoogleCloudPlatform/kubernetes","homepage":"http://kubernetes.io","size":75305,"stargazers_count":6205,"watchers_count":6205,"language":"Go","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":1080,"mirror_url":null,"open_issues_count":682,"forks":1080,"open_issues":682,"watchers":6205,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/4375"},"html":{"href":"https://github.com/GoogleCloudPlatform/kubernetes/pull/4375"},"issue":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/4375"},"comments":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/4375/comments"},"review_comments":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/4375/comments"},"review_comment":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/4375/commits"},"statuses":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/statuses/98da984f3fa15e1da57d3f389cc35227fb28b533"}}}}