Merge pull request github#188 from github/introduce-v3-media-type

pengwynn · pengwynn · commit b182df24f64a · 2012-12-18T07:33:18.000-08:00
Document v3 media type, emails response
diff --git a/content/index.md b/content/index.md
@@ -24,7 +24,7 @@ to the actual date.
 We consider the "beta" API unchangeable.  [File a support issue](https://github.com/contact)
 if you have problems.
 
-#### Expected Changes <a name="changes"></a>
+#### Expected Changes
 
 These changes are _not_ implemented, just planned for the next major API version.
 
@@ -42,19 +42,10 @@ objects.
 * `[ ]` Use the `private` attribute when creating a private repository,
   instead of setting `public` to false.
 * `[ ]` Use JSON to POST to the "repos/:owner/:repo/forks" endpoint, instead of a query string.
-* `[ ]` User Emails come back as a hash instead of a string.
-
-        {"email": "email@whatev.com", "state": "verified"}
+* `[✓]` <del>User Emails come back [as a hash][v3-email] instead of a string.</del>
 
 ### Breaking Beta Changes
 
-##### August 30, 2012
-* Added `repo:status` scope
-* Added Status API
-
-##### August 7, 2012
-* Clarified watching/stargazing
-
 ##### June 12, 2012:
 * Removed API v1 support
 * Removed API v2 support
@@ -77,3 +68,5 @@ objects.
   returned in the Link header instead.
 * JSON-P response has completely changed to a more consistent format.
 * Starring gists now uses PUT verb (instead of POST) and returns 204.
+
+[v3-email]: /v3/users/emails/#future-response
diff --git a/content/v3/media.md b/content/v3/media.md
@@ -47,7 +47,19 @@ for the `X-GitHub-Media-Type` header:
     HTTP/1.1 200 OK
     X-GitHub-Media-Type: github.v3; param=full; format=json
 
-For specifics on versions, check the [API changelog](/v3/changelog).
+
+## API v3 media type and the future
+
+Ultimately, we aim for a version-less, [Hypermedia][hypermedia]-driven API.
+Before we get there, we [expect a few changes][expected-changes]. As we roll
+out these changes, certain methods will support the API v3 media type:
+
+    application/vnd.github.v3
+
+We'll clearly mark those methods that publicly support the v3 media type. 
+
+**NOTE:** _Using the v3 media type for methods other than those marked may yield 
+unexpected results._
 
 ## Comment Body Properties
 
@@ -118,3 +130,5 @@ The Commit, Commit Comparison, and Pull Request resources support
 [gfm]:http://github.github.com/github-flavored-markdown/
 [git-diff]: http://git-scm.com/docs/git-diff
 [git-patch]: http://git-scm.com/docs/git-format-patch
+[hypermedia]: /v3/#hypermedia
+[expected-changes]: /#expected-changes
diff --git a/content/v3/users/emails.md b/content/v3/users/emails.md
@@ -18,6 +18,19 @@ authenticated.
 
 <%= headers 200 %>
 <%= json ["octocat@github.com", "support@github.com"] %>
+<br>
+
+#### Future response
+
+In the final version of the API, this method will return an array of hashes
+with extended information for each email address indicating if the address has
+been verified and if it's the user's primary email address for GitHub.
+
+Until API v3 is finalized, use the `application/vnd.github.v3`
+[mediatype][media-types] to get this response format.
+
+<%= headers 200 %>
+<%= json(:user_email) {|e| [e]} %>
 
 ## Add email address(es)
 
@@ -48,3 +61,5 @@ You can include a single email address or an array of addresses:
 
 <%= headers 204 %>
 
+
+[media-types]: /v3/media
diff --git a/lib/resources.rb b/lib/resources.rb
@@ -1014,6 +1014,12 @@ def text_html(response, status, head = {})
       "C",
       "C++"
     ]
+
+    USER_EMAIL = {
+      :email    => "octocat@github.com",
+      :verified => true,
+      :primary  => true
+    }
   end
 end
 
