{"action":"created","comment":{"url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/pulls/comments/32115695","id":32115695,"diff_hunk":"@@ -0,0 +1,115 @@\n+---\n+title: Semantically Rich APIs\n+excerpt: Fostering Creativity with Semantically Rich APIs\n+layout: post\n+date: 2015-06-09 00:00:00 +0200\n+author: stephen\n+published: true\n+---\n+\n+In a recent post on our blog, Kyle Fuller [wrote about](http://blog.apiary.io/2015/06/04/Hyperdrive/) the benefits of decoupling semantics from implementation for building better API clients. This post aims to explore how this decoupled approach also benefits the API design process, specifically around freeing the produces and consumers to be more creative with semantically rich APIs.\n+\n+## The Difficulty with Common Approaches\n+\n+Many modern approaches in designing and building APIs couple not only clients and servers to implementation details, but we also couple thought, creativity, and shared understanding to that implementation. Coupling servers and clients is a problem that is easily seen, and in theory no one wants a coupled approach. Kyle Fuller wrote in his post:\n+\n+> Imagine entering an API without knowing about any implementation details, but instead just understanding the semantics of the API. We can get the implementation details of the API at run-time to allow us to change them at any point.\n+\n+In waiting until runtime to get these implementation details, Hyperdrive allows for building clients that are highly evolvable and don't break when things are changed on the server.\n+\n+Coupling hinders API evolvability—among other things—but it also hinders API design and creativity for designers and consumers. It is a subtle impedance we overlook because of the distance we've made it in HTTP APIs and because the spectrum of frameworks, libraries, and tools promote this coupled thinking.","path":"_posts/2015-06-09-Fostering-Creativity-with-Semantically-Rich-APIs.md","position":20,"original_position":20,"commit_id":"d560f6e46cb6f4d0f4fbcea2b70f54e41519ccd9","original_commit_id":"d560f6e46cb6f4d0f4fbcea2b70f54e41519ccd9","user":{"login":"fosrias","id":73336,"avatar_url":"https://avatars.githubusercontent.com/u/73336?v=3","gravatar_id":"","url":"https://api.github.com/users/fosrias","html_url":"https://github.com/fosrias","followers_url":"https://api.github.com/users/fosrias/followers","following_url":"https://api.github.com/users/fosrias/following{/other_user}","gists_url":"https://api.github.com/users/fosrias/gists{/gist_id}","starred_url":"https://api.github.com/users/fosrias/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fosrias/subscriptions","organizations_url":"https://api.github.com/users/fosrias/orgs","repos_url":"https://api.github.com/users/fosrias/repos","events_url":"https://api.github.com/users/fosrias/events{/privacy}","received_events_url":"https://api.github.com/users/fosrias/received_events","type":"User","site_admin":false},"body":"re word \"the distance we've made ...\". Do you mean the progress we have made in or something else?","created_at":"2015-06-10T13:19:44Z","updated_at":"2015-06-10T13:19:44Z","html_url":"https://github.com/apiaryio/apiaryio.github.com/pull/62#discussion_r32115695","pull_request_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/pulls/62","_links":{"self":{"href":"https://api.github.com/repos/apiaryio/apiaryio.github.com/pulls/comments/32115695"},"html":{"href":"https://github.com/apiaryio/apiaryio.github.com/pull/62#discussion_r32115695"},"pull_request":{"href":"https://api.github.com/repos/apiaryio/apiaryio.github.com/pulls/62"}}},"pull_request":{"url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/pulls/62","id":37259512,"html_url":"https://github.com/apiaryio/apiaryio.github.com/pull/62","diff_url":"https://github.com/apiaryio/apiaryio.github.com/pull/62.diff","patch_url":"https://github.com/apiaryio/apiaryio.github.com/pull/62.patch","issue_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/issues/62","number":62,"state":"open","locked":false,"title":"Semantically Rich APIs","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":"@amaladolcevita This is a rough draft. I'm still reading through it and polishing it up, but wanted to get it to you as soon as I could to get your thoughts.","created_at":"2015-06-09T14:31:49Z","updated_at":"2015-06-10T13:19:44Z","closed_at":null,"merged_at":null,"merge_commit_sha":"d96123fc3ac27deb297d6a27427ad07b1b9aba34","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/pulls/62/commits","review_comments_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/pulls/62/comments","review_comment_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/pulls/comments{/number}","comments_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/issues/62/comments","statuses_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/statuses/d560f6e46cb6f4d0f4fbcea2b70f54e41519ccd9","head":{"label":"apiaryio:smizell/semantically-rich-apis","ref":"smizell/semantically-rich-apis","sha":"d560f6e46cb6f4d0f4fbcea2b70f54e41519ccd9","user":{"login":"apiaryio","id":765943,"avatar_url":"https://avatars.githubusercontent.com/u/765943?v=3","gravatar_id":"","url":"https://api.github.com/users/apiaryio","html_url":"https://github.com/apiaryio","followers_url":"https://api.github.com/users/apiaryio/followers","following_url":"https://api.github.com/users/apiaryio/following{/other_user}","gists_url":"https://api.github.com/users/apiaryio/gists{/gist_id}","starred_url":"https://api.github.com/users/apiaryio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apiaryio/subscriptions","organizations_url":"https://api.github.com/users/apiaryio/orgs","repos_url":"https://api.github.com/users/apiaryio/repos","events_url":"https://api.github.com/users/apiaryio/events{/privacy}","received_events_url":"https://api.github.com/users/apiaryio/received_events","type":"Organization","site_admin":false},"repo":{"id":1696866,"name":"apiaryio.github.com","full_name":"apiaryio/apiaryio.github.com","owner":{"login":"apiaryio","id":765943,"avatar_url":"https://avatars.githubusercontent.com/u/765943?v=3","gravatar_id":"","url":"https://api.github.com/users/apiaryio","html_url":"https://github.com/apiaryio","followers_url":"https://api.github.com/users/apiaryio/followers","following_url":"https://api.github.com/users/apiaryio/following{/other_user}","gists_url":"https://api.github.com/users/apiaryio/gists{/gist_id}","starred_url":"https://api.github.com/users/apiaryio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apiaryio/subscriptions","organizations_url":"https://api.github.com/users/apiaryio/orgs","repos_url":"https://api.github.com/users/apiaryio/repos","events_url":"https://api.github.com/users/apiaryio/events{/privacy}","received_events_url":"https://api.github.com/users/apiaryio/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/apiaryio/apiaryio.github.com","description":"Apiary Blog","fork":false,"url":"https://api.github.com/repos/apiaryio/apiaryio.github.com","forks_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/forks","keys_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/keys{/key_id}","collaborators_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/teams","hooks_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/hooks","issue_events_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/issues/events{/number}","events_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/events","assignees_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/assignees{/user}","branches_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/branches{/branch}","tags_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/tags","blobs_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/git/refs{/sha}","trees_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/git/trees{/sha}","statuses_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/statuses/{sha}","languages_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/languages","stargazers_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/stargazers","contributors_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/contributors","subscribers_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/subscribers","subscription_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/subscription","commits_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/commits{/sha}","git_commits_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/git/commits{/sha}","comments_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/comments{/number}","issue_comment_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/issues/comments{/number}","contents_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/contents/{+path}","compare_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/compare/{base}...{head}","merges_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/merges","archive_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/downloads","issues_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/issues{/number}","pulls_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/pulls{/number}","milestones_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/milestones{/number}","notifications_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/labels{/name}","releases_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/releases{/id}","created_at":"2011-05-03T15:39:36Z","updated_at":"2015-05-14T10:14:51Z","pushed_at":"2015-06-09T14:31:50Z","git_url":"git://github.com/apiaryio/apiaryio.github.com.git","ssh_url":"git@github.com:apiaryio/apiaryio.github.com.git","clone_url":"https://github.com/apiaryio/apiaryio.github.com.git","svn_url":"https://github.com/apiaryio/apiaryio.github.com","homepage":"https://blog.apiary.io/","size":20068,"stargazers_count":7,"watchers_count":7,"language":"HTML","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":3,"mirror_url":null,"open_issues_count":1,"forks":3,"open_issues":1,"watchers":7,"default_branch":"master"}},"base":{"label":"apiaryio:master","ref":"master","sha":"5aab11d03a66189c4506b22fa714f3b9b383fccb","user":{"login":"apiaryio","id":765943,"avatar_url":"https://avatars.githubusercontent.com/u/765943?v=3","gravatar_id":"","url":"https://api.github.com/users/apiaryio","html_url":"https://github.com/apiaryio","followers_url":"https://api.github.com/users/apiaryio/followers","following_url":"https://api.github.com/users/apiaryio/following{/other_user}","gists_url":"https://api.github.com/users/apiaryio/gists{/gist_id}","starred_url":"https://api.github.com/users/apiaryio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apiaryio/subscriptions","organizations_url":"https://api.github.com/users/apiaryio/orgs","repos_url":"https://api.github.com/users/apiaryio/repos","events_url":"https://api.github.com/users/apiaryio/events{/privacy}","received_events_url":"https://api.github.com/users/apiaryio/received_events","type":"Organization","site_admin":false},"repo":{"id":1696866,"name":"apiaryio.github.com","full_name":"apiaryio/apiaryio.github.com","owner":{"login":"apiaryio","id":765943,"avatar_url":"https://avatars.githubusercontent.com/u/765943?v=3","gravatar_id":"","url":"https://api.github.com/users/apiaryio","html_url":"https://github.com/apiaryio","followers_url":"https://api.github.com/users/apiaryio/followers","following_url":"https://api.github.com/users/apiaryio/following{/other_user}","gists_url":"https://api.github.com/users/apiaryio/gists{/gist_id}","starred_url":"https://api.github.com/users/apiaryio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apiaryio/subscriptions","organizations_url":"https://api.github.com/users/apiaryio/orgs","repos_url":"https://api.github.com/users/apiaryio/repos","events_url":"https://api.github.com/users/apiaryio/events{/privacy}","received_events_url":"https://api.github.com/users/apiaryio/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/apiaryio/apiaryio.github.com","description":"Apiary Blog","fork":false,"url":"https://api.github.com/repos/apiaryio/apiaryio.github.com","forks_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/forks","keys_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/keys{/key_id}","collaborators_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/teams","hooks_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/hooks","issue_events_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/issues/events{/number}","events_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/events","assignees_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/assignees{/user}","branches_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/branches{/branch}","tags_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/tags","blobs_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/git/refs{/sha}","trees_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/git/trees{/sha}","statuses_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/statuses/{sha}","languages_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/languages","stargazers_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/stargazers","contributors_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/contributors","subscribers_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/subscribers","subscription_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/subscription","commits_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/commits{/sha}","git_commits_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/git/commits{/sha}","comments_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/comments{/number}","issue_comment_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/issues/comments{/number}","contents_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/contents/{+path}","compare_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/compare/{base}...{head}","merges_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/merges","archive_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/downloads","issues_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/issues{/number}","pulls_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/pulls{/number}","milestones_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/milestones{/number}","notifications_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/labels{/name}","releases_url":"https://api.github.com/repos/apiaryio/apiaryio.github.com/releases{/id}","created_at":"2011-05-03T15:39:36Z","updated_at":"2015-05-14T10:14:51Z","pushed_at":"2015-06-09T14:31:50Z","git_url":"git://github.com/apiaryio/apiaryio.github.com.git","ssh_url":"git@github.com:apiaryio/apiaryio.github.com.git","clone_url":"https://github.com/apiaryio/apiaryio.github.com.git","svn_url":"https://github.com/apiaryio/apiaryio.github.com","homepage":"https://blog.apiary.io/","size":20068,"stargazers_count":7,"watchers_count":7,"language":"HTML","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":3,"mirror_url":null,"open_issues_count":1,"forks":3,"open_issues":1,"watchers":7,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/apiaryio/apiaryio.github.com/pulls/62"},"html":{"href":"https://github.com/apiaryio/apiaryio.github.com/pull/62"},"issue":{"href":"https://api.github.com/repos/apiaryio/apiaryio.github.com/issues/62"},"comments":{"href":"https://api.github.com/repos/apiaryio/apiaryio.github.com/issues/62/comments"},"review_comments":{"href":"https://api.github.com/repos/apiaryio/apiaryio.github.com/pulls/62/comments"},"review_comment":{"href":"https://api.github.com/repos/apiaryio/apiaryio.github.com/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/apiaryio/apiaryio.github.com/pulls/62/commits"},"statuses":{"href":"https://api.github.com/repos/apiaryio/apiaryio.github.com/statuses/d560f6e46cb6f4d0f4fbcea2b70f54e41519ccd9"}}}}