{"action":"created","comment":{"url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/comments/59531802","id":59531802,"diff_hunk":"@@ -0,0 +1,57 @@\n+# Resources\n+\n+## {{ book.must }} Avoid Actions — Think About Resources\n+\n+REST is all about your resources, so consider the domain entities that take part in web service interaction, and aim to model your API around these using the standard HTTP methods as operation indicators. For instance, if an application has to lock articles explicitly so that only one user may edit them, create an article lock with PUT or POST instead of using a lock action.\n+\n+Request:\n+\n+    PUT /article-locks/{article-id}\n+\n+The added benefit is that you already have a service for browsing and filtering article locks.\n+\n+## {{ book.should }} Define *useful* resources\n+\n+As a rule of thumb resources should be defined to cover 90% of all its client's use cases. A *useful* resource should\n+contain as much information as necessary, but as little as possible. A great way to support the last 10% is to allow\n+clients to specify their needs for more/less information by supporting filtering and\n+[embedding](../hyper-media/Hypermedia.md#should-allow-embedding-of-complex-subresources).\n+\n+## {{ book.must }} Keep URLs Verb-Free\n+\n+The API describes resources, so the only place where actions should appear is in the HTTP methods.\n+In URLs, use only nouns.\n+\n+## {{ book.must }} Use Domain-Specific Resource Names\n+\n+API resources represent elements of the application’s domain model. Using domain-specific nomenclature for resource names helps developers to understand the functionality and basic semantics of your resources. It also reduces the need for further documentation outside the API definition. For example, “sales-order-items” is superior to “order-items” in that it clearly indicates which business object it represents. Along these lines, “items” is too general.\n+\n+## {{ book.must }} Identify resources and Sub-Resources via Path Segments\n+\n+Basic URL structure:\n+\n+    /{resources}/[resource-id]/{sub-resources}/[sub-resource-id]\n+\n+Examples:\n+\n+    /carts/1681e6b88ec1/items\n+    /carts/1681e6b88ec1/items/1\n+\n+## {{ book.could }} Consider Using (Non-) Nested URLs\n+\n+If a sub-resource is only accessible via its parent resource and may not exists without parent resource, consider using a nested URL structure, for instance:\n+\n+    /carts/1681e6b88ec1/cart-items/1\n+\n+However, if the resource can be accessed directly via its unique id, then the API should expose it as a top-level resource. For example, customer is a collection for sales orders; however, sales orders have globally unique id and some services may choose to access the orders directly, for instance:\n+\n+    /customer/1681e6b88ec1\n+    /sales-order/5273gh3k525a\n+\n+## {{ book.should }} Limit of Resources\n+\n+To keep maintenance manageable, and to avoid violations of the “separation of concern” principle, an API should not expose more than 16 resources. If you exceed 16 resources, first check if you can split them into separate subdomains with distinct APIs.","path":"resources/Resources.md","position":53,"original_position":53,"commit_id":"2842bc53de4122453a226d44e6bc08a3c4aec22a","original_commit_id":"2842bc53de4122453a226d44e6bc08a3c4aec22a","user":{"login":"whiskeysierra","id":429981,"avatar_url":"https://avatars.githubusercontent.com/u/429981?v=3","gravatar_id":"","url":"https://api.github.com/users/whiskeysierra","html_url":"https://github.com/whiskeysierra","followers_url":"https://api.github.com/users/whiskeysierra/followers","following_url":"https://api.github.com/users/whiskeysierra/following{/other_user}","gists_url":"https://api.github.com/users/whiskeysierra/gists{/gist_id}","starred_url":"https://api.github.com/users/whiskeysierra/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/whiskeysierra/subscriptions","organizations_url":"https://api.github.com/users/whiskeysierra/orgs","repos_url":"https://api.github.com/users/whiskeysierra/repos","events_url":"https://api.github.com/users/whiskeysierra/events{/privacy}","received_events_url":"https://api.github.com/users/whiskeysierra/received_events","type":"User","site_admin":false},"body":"> I suppose someone proposed it in the Google doc and it was then simply copied here?\r\n\r\nThat makes sense.","created_at":"2016-04-13T11:26:52Z","updated_at":"2016-04-13T11:26:52Z","html_url":"https://github.com/zalando/restful-api-guidelines/pull/23#discussion_r59531802","pull_request_url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/23","_links":{"self":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/comments/59531802"},"html":{"href":"https://github.com/zalando/restful-api-guidelines/pull/23#discussion_r59531802"},"pull_request":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/23"}}},"pull_request":{"url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/23","id":66296689,"html_url":"https://github.com/zalando/restful-api-guidelines/pull/23","diff_url":"https://github.com/zalando/restful-api-guidelines/pull/23.diff","patch_url":"https://github.com/zalando/restful-api-guidelines/pull/23.patch","issue_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/23","number":23,"state":"open","locked":false,"title":"Introducing resources chapter for resource-specific rules","user":{"login":"fmueller","id":719827,"avatar_url":"https://avatars.githubusercontent.com/u/719827?v=3","gravatar_id":"","url":"https://api.github.com/users/fmueller","html_url":"https://github.com/fmueller","followers_url":"https://api.github.com/users/fmueller/followers","following_url":"https://api.github.com/users/fmueller/following{/other_user}","gists_url":"https://api.github.com/users/fmueller/gists{/gist_id}","starred_url":"https://api.github.com/users/fmueller/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fmueller/subscriptions","organizations_url":"https://api.github.com/users/fmueller/orgs","repos_url":"https://api.github.com/users/fmueller/repos","events_url":"https://api.github.com/users/fmueller/events{/privacy}","received_events_url":"https://api.github.com/users/fmueller/received_events","type":"User","site_admin":false},"body":"Some editorial changes, suggested by @tfrauenstein \r\n\r\nAll resource-related rules are grouped in own chapter.","created_at":"2016-04-13T10:15:01Z","updated_at":"2016-04-13T11:26:52Z","closed_at":null,"merged_at":null,"merge_commit_sha":"2c26e9df7a8aef24f632dfd2aab294766b03c76e","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/23/commits","review_comments_url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/23/comments","review_comment_url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/comments{/number}","comments_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/23/comments","statuses_url":"https://api.github.com/repos/zalando/restful-api-guidelines/statuses/2842bc53de4122453a226d44e6bc08a3c4aec22a","head":{"label":"zalando:resource-chapter","ref":"resource-chapter","sha":"2842bc53de4122453a226d44e6bc08a3c4aec22a","user":{"login":"zalando","id":1564818,"avatar_url":"https://avatars.githubusercontent.com/u/1564818?v=3","gravatar_id":"","url":"https://api.github.com/users/zalando","html_url":"https://github.com/zalando","followers_url":"https://api.github.com/users/zalando/followers","following_url":"https://api.github.com/users/zalando/following{/other_user}","gists_url":"https://api.github.com/users/zalando/gists{/gist_id}","starred_url":"https://api.github.com/users/zalando/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zalando/subscriptions","organizations_url":"https://api.github.com/users/zalando/orgs","repos_url":"https://api.github.com/users/zalando/repos","events_url":"https://api.github.com/users/zalando/events{/privacy}","received_events_url":"https://api.github.com/users/zalando/received_events","type":"Organization","site_admin":false},"repo":{"id":55240856,"name":"restful-api-guidelines","full_name":"zalando/restful-api-guidelines","owner":{"login":"zalando","id":1564818,"avatar_url":"https://avatars.githubusercontent.com/u/1564818?v=3","gravatar_id":"","url":"https://api.github.com/users/zalando","html_url":"https://github.com/zalando","followers_url":"https://api.github.com/users/zalando/followers","following_url":"https://api.github.com/users/zalando/following{/other_user}","gists_url":"https://api.github.com/users/zalando/gists{/gist_id}","starred_url":"https://api.github.com/users/zalando/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zalando/subscriptions","organizations_url":"https://api.github.com/users/zalando/orgs","repos_url":"https://api.github.com/users/zalando/repos","events_url":"https://api.github.com/users/zalando/events{/privacy}","received_events_url":"https://api.github.com/users/zalando/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/zalando/restful-api-guidelines","description":"Guidelines for RESTful APIs at Zalando","fork":false,"url":"https://api.github.com/repos/zalando/restful-api-guidelines","forks_url":"https://api.github.com/repos/zalando/restful-api-guidelines/forks","keys_url":"https://api.github.com/repos/zalando/restful-api-guidelines/keys{/key_id}","collaborators_url":"https://api.github.com/repos/zalando/restful-api-guidelines/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/zalando/restful-api-guidelines/teams","hooks_url":"https://api.github.com/repos/zalando/restful-api-guidelines/hooks","issue_events_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/events{/number}","events_url":"https://api.github.com/repos/zalando/restful-api-guidelines/events","assignees_url":"https://api.github.com/repos/zalando/restful-api-guidelines/assignees{/user}","branches_url":"https://api.github.com/repos/zalando/restful-api-guidelines/branches{/branch}","tags_url":"https://api.github.com/repos/zalando/restful-api-guidelines/tags","blobs_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/refs{/sha}","trees_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/trees{/sha}","statuses_url":"https://api.github.com/repos/zalando/restful-api-guidelines/statuses/{sha}","languages_url":"https://api.github.com/repos/zalando/restful-api-guidelines/languages","stargazers_url":"https://api.github.com/repos/zalando/restful-api-guidelines/stargazers","contributors_url":"https://api.github.com/repos/zalando/restful-api-guidelines/contributors","subscribers_url":"https://api.github.com/repos/zalando/restful-api-guidelines/subscribers","subscription_url":"https://api.github.com/repos/zalando/restful-api-guidelines/subscription","commits_url":"https://api.github.com/repos/zalando/restful-api-guidelines/commits{/sha}","git_commits_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/commits{/sha}","comments_url":"https://api.github.com/repos/zalando/restful-api-guidelines/comments{/number}","issue_comment_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/comments{/number}","contents_url":"https://api.github.com/repos/zalando/restful-api-guidelines/contents/{+path}","compare_url":"https://api.github.com/repos/zalando/restful-api-guidelines/compare/{base}...{head}","merges_url":"https://api.github.com/repos/zalando/restful-api-guidelines/merges","archive_url":"https://api.github.com/repos/zalando/restful-api-guidelines/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/zalando/restful-api-guidelines/downloads","issues_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues{/number}","pulls_url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls{/number}","milestones_url":"https://api.github.com/repos/zalando/restful-api-guidelines/milestones{/number}","notifications_url":"https://api.github.com/repos/zalando/restful-api-guidelines/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/zalando/restful-api-guidelines/labels{/name}","releases_url":"https://api.github.com/repos/zalando/restful-api-guidelines/releases{/id}","deployments_url":"https://api.github.com/repos/zalando/restful-api-guidelines/deployments","created_at":"2016-04-01T15:06:54Z","updated_at":"2016-04-12T19:27:58Z","pushed_at":"2016-04-13T11:25:12Z","git_url":"git://github.com/zalando/restful-api-guidelines.git","ssh_url":"git@github.com:zalando/restful-api-guidelines.git","clone_url":"https://github.com/zalando/restful-api-guidelines.git","svn_url":"https://github.com/zalando/restful-api-guidelines","homepage":"http://zalando.github.io/restful-api-guidelines/","size":1473,"stargazers_count":18,"watchers_count":18,"language":"JavaScript","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":true,"forks_count":4,"mirror_url":null,"open_issues_count":10,"forks":4,"open_issues":10,"watchers":18,"default_branch":"master"}},"base":{"label":"zalando:master","ref":"master","sha":"b4c78e07b3dcd8c688a148a33bef6d716de5cf78","user":{"login":"zalando","id":1564818,"avatar_url":"https://avatars.githubusercontent.com/u/1564818?v=3","gravatar_id":"","url":"https://api.github.com/users/zalando","html_url":"https://github.com/zalando","followers_url":"https://api.github.com/users/zalando/followers","following_url":"https://api.github.com/users/zalando/following{/other_user}","gists_url":"https://api.github.com/users/zalando/gists{/gist_id}","starred_url":"https://api.github.com/users/zalando/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zalando/subscriptions","organizations_url":"https://api.github.com/users/zalando/orgs","repos_url":"https://api.github.com/users/zalando/repos","events_url":"https://api.github.com/users/zalando/events{/privacy}","received_events_url":"https://api.github.com/users/zalando/received_events","type":"Organization","site_admin":false},"repo":{"id":55240856,"name":"restful-api-guidelines","full_name":"zalando/restful-api-guidelines","owner":{"login":"zalando","id":1564818,"avatar_url":"https://avatars.githubusercontent.com/u/1564818?v=3","gravatar_id":"","url":"https://api.github.com/users/zalando","html_url":"https://github.com/zalando","followers_url":"https://api.github.com/users/zalando/followers","following_url":"https://api.github.com/users/zalando/following{/other_user}","gists_url":"https://api.github.com/users/zalando/gists{/gist_id}","starred_url":"https://api.github.com/users/zalando/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zalando/subscriptions","organizations_url":"https://api.github.com/users/zalando/orgs","repos_url":"https://api.github.com/users/zalando/repos","events_url":"https://api.github.com/users/zalando/events{/privacy}","received_events_url":"https://api.github.com/users/zalando/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/zalando/restful-api-guidelines","description":"Guidelines for RESTful APIs at Zalando","fork":false,"url":"https://api.github.com/repos/zalando/restful-api-guidelines","forks_url":"https://api.github.com/repos/zalando/restful-api-guidelines/forks","keys_url":"https://api.github.com/repos/zalando/restful-api-guidelines/keys{/key_id}","collaborators_url":"https://api.github.com/repos/zalando/restful-api-guidelines/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/zalando/restful-api-guidelines/teams","hooks_url":"https://api.github.com/repos/zalando/restful-api-guidelines/hooks","issue_events_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/events{/number}","events_url":"https://api.github.com/repos/zalando/restful-api-guidelines/events","assignees_url":"https://api.github.com/repos/zalando/restful-api-guidelines/assignees{/user}","branches_url":"https://api.github.com/repos/zalando/restful-api-guidelines/branches{/branch}","tags_url":"https://api.github.com/repos/zalando/restful-api-guidelines/tags","blobs_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/refs{/sha}","trees_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/trees{/sha}","statuses_url":"https://api.github.com/repos/zalando/restful-api-guidelines/statuses/{sha}","languages_url":"https://api.github.com/repos/zalando/restful-api-guidelines/languages","stargazers_url":"https://api.github.com/repos/zalando/restful-api-guidelines/stargazers","contributors_url":"https://api.github.com/repos/zalando/restful-api-guidelines/contributors","subscribers_url":"https://api.github.com/repos/zalando/restful-api-guidelines/subscribers","subscription_url":"https://api.github.com/repos/zalando/restful-api-guidelines/subscription","commits_url":"https://api.github.com/repos/zalando/restful-api-guidelines/commits{/sha}","git_commits_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/commits{/sha}","comments_url":"https://api.github.com/repos/zalando/restful-api-guidelines/comments{/number}","issue_comment_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/comments{/number}","contents_url":"https://api.github.com/repos/zalando/restful-api-guidelines/contents/{+path}","compare_url":"https://api.github.com/repos/zalando/restful-api-guidelines/compare/{base}...{head}","merges_url":"https://api.github.com/repos/zalando/restful-api-guidelines/merges","archive_url":"https://api.github.com/repos/zalando/restful-api-guidelines/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/zalando/restful-api-guidelines/downloads","issues_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues{/number}","pulls_url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls{/number}","milestones_url":"https://api.github.com/repos/zalando/restful-api-guidelines/milestones{/number}","notifications_url":"https://api.github.com/repos/zalando/restful-api-guidelines/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/zalando/restful-api-guidelines/labels{/name}","releases_url":"https://api.github.com/repos/zalando/restful-api-guidelines/releases{/id}","deployments_url":"https://api.github.com/repos/zalando/restful-api-guidelines/deployments","created_at":"2016-04-01T15:06:54Z","updated_at":"2016-04-12T19:27:58Z","pushed_at":"2016-04-13T11:25:12Z","git_url":"git://github.com/zalando/restful-api-guidelines.git","ssh_url":"git@github.com:zalando/restful-api-guidelines.git","clone_url":"https://github.com/zalando/restful-api-guidelines.git","svn_url":"https://github.com/zalando/restful-api-guidelines","homepage":"http://zalando.github.io/restful-api-guidelines/","size":1473,"stargazers_count":18,"watchers_count":18,"language":"JavaScript","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":true,"forks_count":4,"mirror_url":null,"open_issues_count":10,"forks":4,"open_issues":10,"watchers":18,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/23"},"html":{"href":"https://github.com/zalando/restful-api-guidelines/pull/23"},"issue":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/23"},"comments":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/23/comments"},"review_comments":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/23/comments"},"review_comment":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/23/commits"},"statuses":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/statuses/2842bc53de4122453a226d44e6bc08a3c4aec22a"}}}}