{"action":"created","comment":{"url":"https://api.github.com/repos/Mendeley/api-design-documentation/pulls/comments/59563245","id":59563245,"diff_hunk":"@@ -75,51 +75,83 @@ Reworked into these six RFCs:\n ####Authentication\n coming shortly  \n \n-####Versioning \n-(this needs further clarifications)\n+####Versioning\n \n **Golden Rule** \n \n-\t\tOnce we've released an API, we must NOT make breaking changes to it\n+    Once we've released an API, we must NOT make breaking changes to it.\n \n-        (even if it's not being used, or if it's only deployed to staging, \n-        or if there's only one client, or if we marked it as beta, \n-        or if all of the clients are sitting in the same room as us, \n-        or if we're really-really-careful-yes-we- really-mean-it-this-time)\n+The Golden Rule **MUST NOT** be broken apart from in *exceptional* circumstances, such as for legal reasons.\n \n+The versioning stategy has changed, existing endpoints using the 'legacy' versioning will continue to be supported until deprecated.\n \n-*Content Negotiation* \n+#####New Versioning Strategy\n+\n+All new endpoints **MUST** have a version number in their URL directly beneath the resource name.\n+\n+    e.g. /documents/v1/<id>\n+\n+Endpoints that include a version within the URL **MUST NOT** include a version within the media type.\n+\n+    application/vnd.mendeley-<RESOURCE_TYPE>+json\n+    e.g. application/vnd.mendeley-document+json\n+    \n+Clients **MUST** send a non-null and non-wildcard Accept header for endpoints that produce content. Clients **MUST** also send a non-null Content-Type header for endpoints that consume content.\n+\n+####Legacy Versioning Strategy\n \n Use HTTP's content negotiation mechanism for versioning. Custom media types are used in the API to let the consumers choose the format of the data they wish to receive. This is done by adding the `Accept` header when you make a request. Media types are specific to resources, allowing them to change independently.  \n \n-\tapplication/vnd.mendeley-<RESOURCE_TYPE>.<VERSION>+json\n-\t\n-\te.g. application/vnd.mendeley-document.1+json.  The \"1\" here is the version number of the representation.\n-\t\n-\t\n+    /<RESOURCE_TYPE>s/<id>\n+    application/vnd.mendeley-<RESOURCE_TYPE>.<VERSION>+json\n+    \n+    e.g. /documents/<id>\n+    application/vnd.mendeley-document.1+json.  The \"1\" here is the version number of the representation.\n+\n Both client and servers are responsible for negotiation to be successful. \n \n **Client Responsibilities** \t\n \n * Clients **MUST** send an appropriate resource Media type in the header \n \t\t* e.g. Accept: application/vnd.mendeley-document.1+json\n \n-\n-**Server Responsibilities**   \t\n+**Server Responsibilities**\n \n * Servers **MUST** respond with a Content-Type header \n-\t\t* e.g. Content-Type: application/vnd.mendeley-document.1+json \t\n-\t\n+\t\t* e.g. Content-Type: application/vnd.mendeley-document.1+json\n+\n+Endpoints that include a version within the media type **MUST NOT** include a version within the URL.\n+\n+###Release Lifecycle\n+\n+All endpoints **MUST** follow the Release Lifecycle, each phase of the lifecycle has a set of rules associated with it.\n+\n+####Alpha\n+During this phase of development endpoints may change without giving notice to internal/external clients. Properties can be added and removed, media types modified and the entire endpoint renamed or removed. \n+\n+####Beta\n+When an endpoint is promoted to the Beta phase clients using the endpoint **MUST** be notified of breaking changes and reasonable notice given to allow development teams to respond to the proposed changes; non-breaking changes can be made at any time without notice.\n \n-####Dates\n+####Release\n+Breaking changes **MUST NOT** be made to Released endpoints; non-breaking changes can be made at any time without notice.\n+If breaking changes are required (for example, to remove an unused property) then a new version of the endpoint must be developed.\n+\n+####Deprecated\n+\n+When a new version of an endpoint is promoted to the Released stage the previous version will be moved to the Deprecated stage. Client teams using the endpoint **MUST** be informed immediately and the deprecation date **MUST** give reasonable time for migration to new endpoints. Client teams still using the endpoint **SHOULD** be reminded of the retirement before the deprecation date.\n+\n+####Retired\n+\n+Retired endpoints, those with a deprecation date in the past, will not be available - the client **MUST** receive either a 410 or 404 status code if the endpoint is requested after this time.","path":"README.md","position":89,"original_position":89,"commit_id":"9561ba9ee71cf393442a1910a949aa51857c7982","original_commit_id":"9561ba9ee71cf393442a1910a949aa51857c7982","user":{"login":"chiastic-security","id":8581980,"avatar_url":"https://avatars.githubusercontent.com/u/8581980?v=3","gravatar_id":"","url":"https://api.github.com/users/chiastic-security","html_url":"https://github.com/chiastic-security","followers_url":"https://api.github.com/users/chiastic-security/followers","following_url":"https://api.github.com/users/chiastic-security/following{/other_user}","gists_url":"https://api.github.com/users/chiastic-security/gists{/gist_id}","starred_url":"https://api.github.com/users/chiastic-security/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chiastic-security/subscriptions","organizations_url":"https://api.github.com/users/chiastic-security/orgs","repos_url":"https://api.github.com/users/chiastic-security/repos","events_url":"https://api.github.com/users/chiastic-security/events{/privacy}","received_events_url":"https://api.github.com/users/chiastic-security/received_events","type":"User","site_admin":false},"body":"Change \"the client must receive\" to \"the server must send\".","created_at":"2016-04-13T14:55:26Z","updated_at":"2016-04-13T14:55:26Z","html_url":"https://github.com/Mendeley/api-design-documentation/pull/3#discussion_r59563245","pull_request_url":"https://api.github.com/repos/Mendeley/api-design-documentation/pulls/3","_links":{"self":{"href":"https://api.github.com/repos/Mendeley/api-design-documentation/pulls/comments/59563245"},"html":{"href":"https://github.com/Mendeley/api-design-documentation/pull/3#discussion_r59563245"},"pull_request":{"href":"https://api.github.com/repos/Mendeley/api-design-documentation/pulls/3"}}},"pull_request":{"url":"https://api.github.com/repos/Mendeley/api-design-documentation/pulls/3","id":66184364,"html_url":"https://github.com/Mendeley/api-design-documentation/pull/3","diff_url":"https://github.com/Mendeley/api-design-documentation/pull/3.diff","patch_url":"https://github.com/Mendeley/api-design-documentation/pull/3.patch","issue_url":"https://api.github.com/repos/Mendeley/api-design-documentation/issues/3","number":3,"state":"open","locked":false,"title":"Add updated versioning strategy","user":{"login":"chrishowell","id":1407962,"avatar_url":"https://avatars.githubusercontent.com/u/1407962?v=3","gravatar_id":"","url":"https://api.github.com/users/chrishowell","html_url":"https://github.com/chrishowell","followers_url":"https://api.github.com/users/chrishowell/followers","following_url":"https://api.github.com/users/chrishowell/following{/other_user}","gists_url":"https://api.github.com/users/chrishowell/gists{/gist_id}","starred_url":"https://api.github.com/users/chrishowell/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chrishowell/subscriptions","organizations_url":"https://api.github.com/users/chrishowell/orgs","repos_url":"https://api.github.com/users/chrishowell/repos","events_url":"https://api.github.com/users/chrishowell/events{/privacy}","received_events_url":"https://api.github.com/users/chrishowell/received_events","type":"User","site_admin":false},"body":"","created_at":"2016-04-12T16:06:25Z","updated_at":"2016-04-13T14:55:26Z","closed_at":null,"merged_at":null,"merge_commit_sha":"4e00d433f32f8912f2dd9421acde0b35046e25a5","assignee":{"login":"chiastic-security","id":8581980,"avatar_url":"https://avatars.githubusercontent.com/u/8581980?v=3","gravatar_id":"","url":"https://api.github.com/users/chiastic-security","html_url":"https://github.com/chiastic-security","followers_url":"https://api.github.com/users/chiastic-security/followers","following_url":"https://api.github.com/users/chiastic-security/following{/other_user}","gists_url":"https://api.github.com/users/chiastic-security/gists{/gist_id}","starred_url":"https://api.github.com/users/chiastic-security/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chiastic-security/subscriptions","organizations_url":"https://api.github.com/users/chiastic-security/orgs","repos_url":"https://api.github.com/users/chiastic-security/repos","events_url":"https://api.github.com/users/chiastic-security/events{/privacy}","received_events_url":"https://api.github.com/users/chiastic-security/received_events","type":"User","site_admin":false},"milestone":null,"commits_url":"https://api.github.com/repos/Mendeley/api-design-documentation/pulls/3/commits","review_comments_url":"https://api.github.com/repos/Mendeley/api-design-documentation/pulls/3/comments","review_comment_url":"https://api.github.com/repos/Mendeley/api-design-documentation/pulls/comments{/number}","comments_url":"https://api.github.com/repos/Mendeley/api-design-documentation/issues/3/comments","statuses_url":"https://api.github.com/repos/Mendeley/api-design-documentation/statuses/9561ba9ee71cf393442a1910a949aa51857c7982","head":{"label":"Mendeley:versioning","ref":"versioning","sha":"9561ba9ee71cf393442a1910a949aa51857c7982","user":{"login":"Mendeley","id":360932,"avatar_url":"https://avatars.githubusercontent.com/u/360932?v=3","gravatar_id":"","url":"https://api.github.com/users/Mendeley","html_url":"https://github.com/Mendeley","followers_url":"https://api.github.com/users/Mendeley/followers","following_url":"https://api.github.com/users/Mendeley/following{/other_user}","gists_url":"https://api.github.com/users/Mendeley/gists{/gist_id}","starred_url":"https://api.github.com/users/Mendeley/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Mendeley/subscriptions","organizations_url":"https://api.github.com/users/Mendeley/orgs","repos_url":"https://api.github.com/users/Mendeley/repos","events_url":"https://api.github.com/users/Mendeley/events{/privacy}","received_events_url":"https://api.github.com/users/Mendeley/received_events","type":"Organization","site_admin":false},"repo":{"id":43823418,"name":"api-design-documentation","full_name":"Mendeley/api-design-documentation","owner":{"login":"Mendeley","id":360932,"avatar_url":"https://avatars.githubusercontent.com/u/360932?v=3","gravatar_id":"","url":"https://api.github.com/users/Mendeley","html_url":"https://github.com/Mendeley","followers_url":"https://api.github.com/users/Mendeley/followers","following_url":"https://api.github.com/users/Mendeley/following{/other_user}","gists_url":"https://api.github.com/users/Mendeley/gists{/gist_id}","starred_url":"https://api.github.com/users/Mendeley/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Mendeley/subscriptions","organizations_url":"https://api.github.com/users/Mendeley/orgs","repos_url":"https://api.github.com/users/Mendeley/repos","events_url":"https://api.github.com/users/Mendeley/events{/privacy}","received_events_url":"https://api.github.com/users/Mendeley/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/Mendeley/api-design-documentation","description":"Contains documentation on suggested API design and best practices. ","fork":false,"url":"https://api.github.com/repos/Mendeley/api-design-documentation","forks_url":"https://api.github.com/repos/Mendeley/api-design-documentation/forks","keys_url":"https://api.github.com/repos/Mendeley/api-design-documentation/keys{/key_id}","collaborators_url":"https://api.github.com/repos/Mendeley/api-design-documentation/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/Mendeley/api-design-documentation/teams","hooks_url":"https://api.github.com/repos/Mendeley/api-design-documentation/hooks","issue_events_url":"https://api.github.com/repos/Mendeley/api-design-documentation/issues/events{/number}","events_url":"https://api.github.com/repos/Mendeley/api-design-documentation/events","assignees_url":"https://api.github.com/repos/Mendeley/api-design-documentation/assignees{/user}","branches_url":"https://api.github.com/repos/Mendeley/api-design-documentation/branches{/branch}","tags_url":"https://api.github.com/repos/Mendeley/api-design-documentation/tags","blobs_url":"https://api.github.com/repos/Mendeley/api-design-documentation/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/Mendeley/api-design-documentation/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/Mendeley/api-design-documentation/git/refs{/sha}","trees_url":"https://api.github.com/repos/Mendeley/api-design-documentation/git/trees{/sha}","statuses_url":"https://api.github.com/repos/Mendeley/api-design-documentation/statuses/{sha}","languages_url":"https://api.github.com/repos/Mendeley/api-design-documentation/languages","stargazers_url":"https://api.github.com/repos/Mendeley/api-design-documentation/stargazers","contributors_url":"https://api.github.com/repos/Mendeley/api-design-documentation/contributors","subscribers_url":"https://api.github.com/repos/Mendeley/api-design-documentation/subscribers","subscription_url":"https://api.github.com/repos/Mendeley/api-design-documentation/subscription","commits_url":"https://api.github.com/repos/Mendeley/api-design-documentation/commits{/sha}","git_commits_url":"https://api.github.com/repos/Mendeley/api-design-documentation/git/commits{/sha}","comments_url":"https://api.github.com/repos/Mendeley/api-design-documentation/comments{/number}","issue_comment_url":"https://api.github.com/repos/Mendeley/api-design-documentation/issues/comments{/number}","contents_url":"https://api.github.com/repos/Mendeley/api-design-documentation/contents/{+path}","compare_url":"https://api.github.com/repos/Mendeley/api-design-documentation/compare/{base}...{head}","merges_url":"https://api.github.com/repos/Mendeley/api-design-documentation/merges","archive_url":"https://api.github.com/repos/Mendeley/api-design-documentation/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/Mendeley/api-design-documentation/downloads","issues_url":"https://api.github.com/repos/Mendeley/api-design-documentation/issues{/number}","pulls_url":"https://api.github.com/repos/Mendeley/api-design-documentation/pulls{/number}","milestones_url":"https://api.github.com/repos/Mendeley/api-design-documentation/milestones{/number}","notifications_url":"https://api.github.com/repos/Mendeley/api-design-documentation/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/Mendeley/api-design-documentation/labels{/name}","releases_url":"https://api.github.com/repos/Mendeley/api-design-documentation/releases{/id}","deployments_url":"https://api.github.com/repos/Mendeley/api-design-documentation/deployments","created_at":"2015-10-07T14:58:31Z","updated_at":"2016-03-14T15:13:58Z","pushed_at":"2016-04-12T16:06:25Z","git_url":"git://github.com/Mendeley/api-design-documentation.git","ssh_url":"git@github.com:Mendeley/api-design-documentation.git","clone_url":"https://github.com/Mendeley/api-design-documentation.git","svn_url":"https://github.com/Mendeley/api-design-documentation","homepage":null,"size":2098,"stargazers_count":11,"watchers_count":11,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":2,"mirror_url":null,"open_issues_count":1,"forks":2,"open_issues":1,"watchers":11,"default_branch":"master"}},"base":{"label":"Mendeley:master","ref":"master","sha":"4d166c66c3db7214382a9ddbc05ab8540e25c74d","user":{"login":"Mendeley","id":360932,"avatar_url":"https://avatars.githubusercontent.com/u/360932?v=3","gravatar_id":"","url":"https://api.github.com/users/Mendeley","html_url":"https://github.com/Mendeley","followers_url":"https://api.github.com/users/Mendeley/followers","following_url":"https://api.github.com/users/Mendeley/following{/other_user}","gists_url":"https://api.github.com/users/Mendeley/gists{/gist_id}","starred_url":"https://api.github.com/users/Mendeley/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Mendeley/subscriptions","organizations_url":"https://api.github.com/users/Mendeley/orgs","repos_url":"https://api.github.com/users/Mendeley/repos","events_url":"https://api.github.com/users/Mendeley/events{/privacy}","received_events_url":"https://api.github.com/users/Mendeley/received_events","type":"Organization","site_admin":false},"repo":{"id":43823418,"name":"api-design-documentation","full_name":"Mendeley/api-design-documentation","owner":{"login":"Mendeley","id":360932,"avatar_url":"https://avatars.githubusercontent.com/u/360932?v=3","gravatar_id":"","url":"https://api.github.com/users/Mendeley","html_url":"https://github.com/Mendeley","followers_url":"https://api.github.com/users/Mendeley/followers","following_url":"https://api.github.com/users/Mendeley/following{/other_user}","gists_url":"https://api.github.com/users/Mendeley/gists{/gist_id}","starred_url":"https://api.github.com/users/Mendeley/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Mendeley/subscriptions","organizations_url":"https://api.github.com/users/Mendeley/orgs","repos_url":"https://api.github.com/users/Mendeley/repos","events_url":"https://api.github.com/users/Mendeley/events{/privacy}","received_events_url":"https://api.github.com/users/Mendeley/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/Mendeley/api-design-documentation","description":"Contains documentation on suggested API design and best practices. ","fork":false,"url":"https://api.github.com/repos/Mendeley/api-design-documentation","forks_url":"https://api.github.com/repos/Mendeley/api-design-documentation/forks","keys_url":"https://api.github.com/repos/Mendeley/api-design-documentation/keys{/key_id}","collaborators_url":"https://api.github.com/repos/Mendeley/api-design-documentation/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/Mendeley/api-design-documentation/teams","hooks_url":"https://api.github.com/repos/Mendeley/api-design-documentation/hooks","issue_events_url":"https://api.github.com/repos/Mendeley/api-design-documentation/issues/events{/number}","events_url":"https://api.github.com/repos/Mendeley/api-design-documentation/events","assignees_url":"https://api.github.com/repos/Mendeley/api-design-documentation/assignees{/user}","branches_url":"https://api.github.com/repos/Mendeley/api-design-documentation/branches{/branch}","tags_url":"https://api.github.com/repos/Mendeley/api-design-documentation/tags","blobs_url":"https://api.github.com/repos/Mendeley/api-design-documentation/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/Mendeley/api-design-documentation/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/Mendeley/api-design-documentation/git/refs{/sha}","trees_url":"https://api.github.com/repos/Mendeley/api-design-documentation/git/trees{/sha}","statuses_url":"https://api.github.com/repos/Mendeley/api-design-documentation/statuses/{sha}","languages_url":"https://api.github.com/repos/Mendeley/api-design-documentation/languages","stargazers_url":"https://api.github.com/repos/Mendeley/api-design-documentation/stargazers","contributors_url":"https://api.github.com/repos/Mendeley/api-design-documentation/contributors","subscribers_url":"https://api.github.com/repos/Mendeley/api-design-documentation/subscribers","subscription_url":"https://api.github.com/repos/Mendeley/api-design-documentation/subscription","commits_url":"https://api.github.com/repos/Mendeley/api-design-documentation/commits{/sha}","git_commits_url":"https://api.github.com/repos/Mendeley/api-design-documentation/git/commits{/sha}","comments_url":"https://api.github.com/repos/Mendeley/api-design-documentation/comments{/number}","issue_comment_url":"https://api.github.com/repos/Mendeley/api-design-documentation/issues/comments{/number}","contents_url":"https://api.github.com/repos/Mendeley/api-design-documentation/contents/{+path}","compare_url":"https://api.github.com/repos/Mendeley/api-design-documentation/compare/{base}...{head}","merges_url":"https://api.github.com/repos/Mendeley/api-design-documentation/merges","archive_url":"https://api.github.com/repos/Mendeley/api-design-documentation/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/Mendeley/api-design-documentation/downloads","issues_url":"https://api.github.com/repos/Mendeley/api-design-documentation/issues{/number}","pulls_url":"https://api.github.com/repos/Mendeley/api-design-documentation/pulls{/number}","milestones_url":"https://api.github.com/repos/Mendeley/api-design-documentation/milestones{/number}","notifications_url":"https://api.github.com/repos/Mendeley/api-design-documentation/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/Mendeley/api-design-documentation/labels{/name}","releases_url":"https://api.github.com/repos/Mendeley/api-design-documentation/releases{/id}","deployments_url":"https://api.github.com/repos/Mendeley/api-design-documentation/deployments","created_at":"2015-10-07T14:58:31Z","updated_at":"2016-03-14T15:13:58Z","pushed_at":"2016-04-12T16:06:25Z","git_url":"git://github.com/Mendeley/api-design-documentation.git","ssh_url":"git@github.com:Mendeley/api-design-documentation.git","clone_url":"https://github.com/Mendeley/api-design-documentation.git","svn_url":"https://github.com/Mendeley/api-design-documentation","homepage":null,"size":2098,"stargazers_count":11,"watchers_count":11,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":2,"mirror_url":null,"open_issues_count":1,"forks":2,"open_issues":1,"watchers":11,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/Mendeley/api-design-documentation/pulls/3"},"html":{"href":"https://github.com/Mendeley/api-design-documentation/pull/3"},"issue":{"href":"https://api.github.com/repos/Mendeley/api-design-documentation/issues/3"},"comments":{"href":"https://api.github.com/repos/Mendeley/api-design-documentation/issues/3/comments"},"review_comments":{"href":"https://api.github.com/repos/Mendeley/api-design-documentation/pulls/3/comments"},"review_comment":{"href":"https://api.github.com/repos/Mendeley/api-design-documentation/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/Mendeley/api-design-documentation/pulls/3/commits"},"statuses":{"href":"https://api.github.com/repos/Mendeley/api-design-documentation/statuses/9561ba9ee71cf393442a1910a949aa51857c7982"}}}}