{"action":"opened","issue":{"url":"https://api.github.com/repos/AusDTO/apiguide/issues/39","labels_url":"https://api.github.com/repos/AusDTO/apiguide/issues/39/labels{/name}","comments_url":"https://api.github.com/repos/AusDTO/apiguide/issues/39/comments","events_url":"https://api.github.com/repos/AusDTO/apiguide/issues/39/events","html_url":"https://github.com/AusDTO/apiguide/issues/39","id":100549470,"number":39,"title":"principles/granularity.rst: question about optimum granularity?","user":{"login":"monkeypants","id":532596,"avatar_url":"https://avatars.githubusercontent.com/u/532596?v=3","gravatar_id":"","url":"https://api.github.com/users/monkeypants","html_url":"https://github.com/monkeypants","followers_url":"https://api.github.com/users/monkeypants/followers","following_url":"https://api.github.com/users/monkeypants/following{/other_user}","gists_url":"https://api.github.com/users/monkeypants/gists{/gist_id}","starred_url":"https://api.github.com/users/monkeypants/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/monkeypants/subscriptions","organizations_url":"https://api.github.com/users/monkeypants/orgs","repos_url":"https://api.github.com/users/monkeypants/repos","events_url":"https://api.github.com/users/monkeypants/events{/privacy}","received_events_url":"https://api.github.com/users/monkeypants/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/AusDTO/apiguide/labels/help%20wanted","name":"help wanted","color":"159818"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":0,"created_at":"2015-08-12T13:53:05Z","updated_at":"2015-08-12T13:53:05Z","closed_at":null,"body":"I have a nagging doubt about this statement:\r\n\r\n> APIs should be designed at the lowest practical level of granularity because this makes each service simpler and allows them to be combined in ways that suit the consumer.\r\n\r\nI think it maybe more accurate to say \"finest level of granularity that is cohesive and coherent\".\r\n\r\nWhy split this particular hair? if you start with a 1:1 mapping of the paper form (for example), i.e. clearly to coarse, and then start breaking it down into sensible chunks that make sense in a wider context, the cohesion and coherence of those chunks is better than the original 1:1 mapping.  Great, you're winning... But if you take it to far, past the point of maximum cohesiveness, then not only do you start becoming less coherent, you also make a bad compromise with \"distributed computing issues\"; network reliability/latency/bandwidth issues, security/topology/administrative issues.\r\n\r\nThere's clearly a sweet spot, but it's not easy to define. Comments/suggestion/arguments welcome...\r\n"}}