{"action":"created","comment":{"url":"https://api.github.com/repos/IntrepidPursuits/sherpa/pulls/comments/36590974","id":36590974,"diff_hunk":"@@ -0,0 +1,7 @@\n+# Versioning\n+\n+Functionality provided by an API inevitably changes over time, and it’s sometimes necessary to make breaking, backwards-incompatible changes. In contrast to web app users, mobile app users must upgrade their software to take advantage of new functionality, and there is a period of overlap and adoption where two versions of a client are in circulation. It is beneficial to think about upgrade strategies early in your API’s development, and there are a few different approaches.\n+\n+The most common approach is to prefix URIs with a version, e.g. ‘/v1/method’. This allows clients that are configured to use a particular version of an API to continue using it after a new version of the API is released with a different prefix. Facebook is an example of an API that is versioned this way.\n+","path":"mobile_api_guidance.md","position":6,"original_position":6,"commit_id":"183547e9f7f3b1cf24c46280b94c474800672553","original_commit_id":"09d09b8c0b2f0a612f76d81422329371847493ff","user":{"login":"intrepidmatt","id":2279193,"avatar_url":"https://avatars.githubusercontent.com/u/2279193?v=3","gravatar_id":"","url":"https://api.github.com/users/intrepidmatt","html_url":"https://github.com/intrepidmatt","followers_url":"https://api.github.com/users/intrepidmatt/followers","following_url":"https://api.github.com/users/intrepidmatt/following{/other_user}","gists_url":"https://api.github.com/users/intrepidmatt/gists{/gist_id}","starred_url":"https://api.github.com/users/intrepidmatt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/intrepidmatt/subscriptions","organizations_url":"https://api.github.com/users/intrepidmatt/orgs","repos_url":"https://api.github.com/users/intrepidmatt/repos","events_url":"https://api.github.com/users/intrepidmatt/events{/privacy}","received_events_url":"https://api.github.com/users/intrepidmatt/received_events","type":"User","site_admin":false},"body":"I prefer the client to be explicit about the version it intends to use as opposed to the server having to do a mapping from client to API version.","created_at":"2015-08-09T17:28:03Z","updated_at":"2015-08-09T17:28:03Z","html_url":"https://github.com/IntrepidPursuits/sherpa/pull/1#discussion_r36590974","pull_request_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/pulls/1","_links":{"self":{"href":"https://api.github.com/repos/IntrepidPursuits/sherpa/pulls/comments/36590974"},"html":{"href":"https://github.com/IntrepidPursuits/sherpa/pull/1#discussion_r36590974"},"pull_request":{"href":"https://api.github.com/repos/IntrepidPursuits/sherpa/pulls/1"}}},"pull_request":{"url":"https://api.github.com/repos/IntrepidPursuits/sherpa/pulls/1","id":40766947,"html_url":"https://github.com/IntrepidPursuits/sherpa/pull/1","diff_url":"https://github.com/IntrepidPursuits/sherpa/pull/1.diff","patch_url":"https://github.com/IntrepidPursuits/sherpa/pull/1.patch","issue_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/issues/1","number":1,"state":"open","locked":false,"title":"Add a mobile API guidance document; versioning guidance.","user":{"login":"intrepidmatt","id":2279193,"avatar_url":"https://avatars.githubusercontent.com/u/2279193?v=3","gravatar_id":"","url":"https://api.github.com/users/intrepidmatt","html_url":"https://github.com/intrepidmatt","followers_url":"https://api.github.com/users/intrepidmatt/followers","following_url":"https://api.github.com/users/intrepidmatt/following{/other_user}","gists_url":"https://api.github.com/users/intrepidmatt/gists{/gist_id}","starred_url":"https://api.github.com/users/intrepidmatt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/intrepidmatt/subscriptions","organizations_url":"https://api.github.com/users/intrepidmatt/orgs","repos_url":"https://api.github.com/users/intrepidmatt/repos","events_url":"https://api.github.com/users/intrepidmatt/events{/privacy}","received_events_url":"https://api.github.com/users/intrepidmatt/received_events","type":"User","site_admin":false},"body":"Added a link from the README to a stub for mobile API guidance, meant for our backend team and also clients that are building their own APIs.","created_at":"2015-07-24T11:41:57Z","updated_at":"2015-08-09T17:28:03Z","closed_at":null,"merged_at":null,"merge_commit_sha":"6ec851e41216f7e1a0f9aa6dbfd84f8c179ebebe","assignee":{"login":"brightredchilli","id":751191,"avatar_url":"https://avatars.githubusercontent.com/u/751191?v=3","gravatar_id":"","url":"https://api.github.com/users/brightredchilli","html_url":"https://github.com/brightredchilli","followers_url":"https://api.github.com/users/brightredchilli/followers","following_url":"https://api.github.com/users/brightredchilli/following{/other_user}","gists_url":"https://api.github.com/users/brightredchilli/gists{/gist_id}","starred_url":"https://api.github.com/users/brightredchilli/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/brightredchilli/subscriptions","organizations_url":"https://api.github.com/users/brightredchilli/orgs","repos_url":"https://api.github.com/users/brightredchilli/repos","events_url":"https://api.github.com/users/brightredchilli/events{/privacy}","received_events_url":"https://api.github.com/users/brightredchilli/received_events","type":"User","site_admin":false},"milestone":null,"commits_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/pulls/1/commits","review_comments_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/pulls/1/comments","review_comment_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/pulls/comments{/number}","comments_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/issues/1/comments","statuses_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/statuses/183547e9f7f3b1cf24c46280b94c474800672553","head":{"label":"IntrepidPursuits:mobile-api-guidance","ref":"mobile-api-guidance","sha":"183547e9f7f3b1cf24c46280b94c474800672553","user":{"login":"IntrepidPursuits","id":2151424,"avatar_url":"https://avatars.githubusercontent.com/u/2151424?v=3","gravatar_id":"","url":"https://api.github.com/users/IntrepidPursuits","html_url":"https://github.com/IntrepidPursuits","followers_url":"https://api.github.com/users/IntrepidPursuits/followers","following_url":"https://api.github.com/users/IntrepidPursuits/following{/other_user}","gists_url":"https://api.github.com/users/IntrepidPursuits/gists{/gist_id}","starred_url":"https://api.github.com/users/IntrepidPursuits/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/IntrepidPursuits/subscriptions","organizations_url":"https://api.github.com/users/IntrepidPursuits/orgs","repos_url":"https://api.github.com/users/IntrepidPursuits/repos","events_url":"https://api.github.com/users/IntrepidPursuits/events{/privacy}","received_events_url":"https://api.github.com/users/IntrepidPursuits/received_events","type":"Organization","site_admin":false},"repo":{"id":39629319,"name":"sherpa","full_name":"IntrepidPursuits/sherpa","owner":{"login":"IntrepidPursuits","id":2151424,"avatar_url":"https://avatars.githubusercontent.com/u/2151424?v=3","gravatar_id":"","url":"https://api.github.com/users/IntrepidPursuits","html_url":"https://github.com/IntrepidPursuits","followers_url":"https://api.github.com/users/IntrepidPursuits/followers","following_url":"https://api.github.com/users/IntrepidPursuits/following{/other_user}","gists_url":"https://api.github.com/users/IntrepidPursuits/gists{/gist_id}","starred_url":"https://api.github.com/users/IntrepidPursuits/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/IntrepidPursuits/subscriptions","organizations_url":"https://api.github.com/users/IntrepidPursuits/orgs","repos_url":"https://api.github.com/users/IntrepidPursuits/repos","events_url":"https://api.github.com/users/IntrepidPursuits/events{/privacy}","received_events_url":"https://api.github.com/users/IntrepidPursuits/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/IntrepidPursuits/sherpa","description":"Development best practices for Intrepid","fork":false,"url":"https://api.github.com/repos/IntrepidPursuits/sherpa","forks_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/forks","keys_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/keys{/key_id}","collaborators_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/teams","hooks_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/hooks","issue_events_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/issues/events{/number}","events_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/events","assignees_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/assignees{/user}","branches_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/branches{/branch}","tags_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/tags","blobs_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/git/refs{/sha}","trees_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/git/trees{/sha}","statuses_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/statuses/{sha}","languages_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/languages","stargazers_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/stargazers","contributors_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/contributors","subscribers_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/subscribers","subscription_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/subscription","commits_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/commits{/sha}","git_commits_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/git/commits{/sha}","comments_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/comments{/number}","issue_comment_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/issues/comments{/number}","contents_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/contents/{+path}","compare_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/compare/{base}...{head}","merges_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/merges","archive_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/downloads","issues_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/issues{/number}","pulls_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/pulls{/number}","milestones_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/milestones{/number}","notifications_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/labels{/name}","releases_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/releases{/id}","created_at":"2015-07-24T11:31:35Z","updated_at":"2015-07-24T11:31:35Z","pushed_at":"2015-08-09T17:25:03Z","git_url":"git://github.com/IntrepidPursuits/sherpa.git","ssh_url":"git@github.com:IntrepidPursuits/sherpa.git","clone_url":"https://github.com/IntrepidPursuits/sherpa.git","svn_url":"https://github.com/IntrepidPursuits/sherpa","homepage":null,"size":160,"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":"IntrepidPursuits:master","ref":"master","sha":"c12b5d35147043d143e5ffc794b1006836224abe","user":{"login":"IntrepidPursuits","id":2151424,"avatar_url":"https://avatars.githubusercontent.com/u/2151424?v=3","gravatar_id":"","url":"https://api.github.com/users/IntrepidPursuits","html_url":"https://github.com/IntrepidPursuits","followers_url":"https://api.github.com/users/IntrepidPursuits/followers","following_url":"https://api.github.com/users/IntrepidPursuits/following{/other_user}","gists_url":"https://api.github.com/users/IntrepidPursuits/gists{/gist_id}","starred_url":"https://api.github.com/users/IntrepidPursuits/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/IntrepidPursuits/subscriptions","organizations_url":"https://api.github.com/users/IntrepidPursuits/orgs","repos_url":"https://api.github.com/users/IntrepidPursuits/repos","events_url":"https://api.github.com/users/IntrepidPursuits/events{/privacy}","received_events_url":"https://api.github.com/users/IntrepidPursuits/received_events","type":"Organization","site_admin":false},"repo":{"id":39629319,"name":"sherpa","full_name":"IntrepidPursuits/sherpa","owner":{"login":"IntrepidPursuits","id":2151424,"avatar_url":"https://avatars.githubusercontent.com/u/2151424?v=3","gravatar_id":"","url":"https://api.github.com/users/IntrepidPursuits","html_url":"https://github.com/IntrepidPursuits","followers_url":"https://api.github.com/users/IntrepidPursuits/followers","following_url":"https://api.github.com/users/IntrepidPursuits/following{/other_user}","gists_url":"https://api.github.com/users/IntrepidPursuits/gists{/gist_id}","starred_url":"https://api.github.com/users/IntrepidPursuits/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/IntrepidPursuits/subscriptions","organizations_url":"https://api.github.com/users/IntrepidPursuits/orgs","repos_url":"https://api.github.com/users/IntrepidPursuits/repos","events_url":"https://api.github.com/users/IntrepidPursuits/events{/privacy}","received_events_url":"https://api.github.com/users/IntrepidPursuits/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/IntrepidPursuits/sherpa","description":"Development best practices for Intrepid","fork":false,"url":"https://api.github.com/repos/IntrepidPursuits/sherpa","forks_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/forks","keys_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/keys{/key_id}","collaborators_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/teams","hooks_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/hooks","issue_events_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/issues/events{/number}","events_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/events","assignees_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/assignees{/user}","branches_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/branches{/branch}","tags_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/tags","blobs_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/git/refs{/sha}","trees_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/git/trees{/sha}","statuses_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/statuses/{sha}","languages_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/languages","stargazers_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/stargazers","contributors_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/contributors","subscribers_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/subscribers","subscription_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/subscription","commits_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/commits{/sha}","git_commits_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/git/commits{/sha}","comments_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/comments{/number}","issue_comment_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/issues/comments{/number}","contents_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/contents/{+path}","compare_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/compare/{base}...{head}","merges_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/merges","archive_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/downloads","issues_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/issues{/number}","pulls_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/pulls{/number}","milestones_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/milestones{/number}","notifications_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/labels{/name}","releases_url":"https://api.github.com/repos/IntrepidPursuits/sherpa/releases{/id}","created_at":"2015-07-24T11:31:35Z","updated_at":"2015-07-24T11:31:35Z","pushed_at":"2015-08-09T17:25:03Z","git_url":"git://github.com/IntrepidPursuits/sherpa.git","ssh_url":"git@github.com:IntrepidPursuits/sherpa.git","clone_url":"https://github.com/IntrepidPursuits/sherpa.git","svn_url":"https://github.com/IntrepidPursuits/sherpa","homepage":null,"size":160,"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/IntrepidPursuits/sherpa/pulls/1"},"html":{"href":"https://github.com/IntrepidPursuits/sherpa/pull/1"},"issue":{"href":"https://api.github.com/repos/IntrepidPursuits/sherpa/issues/1"},"comments":{"href":"https://api.github.com/repos/IntrepidPursuits/sherpa/issues/1/comments"},"review_comments":{"href":"https://api.github.com/repos/IntrepidPursuits/sherpa/pulls/1/comments"},"review_comment":{"href":"https://api.github.com/repos/IntrepidPursuits/sherpa/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/IntrepidPursuits/sherpa/pulls/1/commits"},"statuses":{"href":"https://api.github.com/repos/IntrepidPursuits/sherpa/statuses/183547e9f7f3b1cf24c46280b94c474800672553"}}}}