Permalink
Browse files

describe new mime type stuff, add a real change log

  • Loading branch information...
1 parent 136941d commit 4caab67b753c0ddbbb6311fc74653f6a0187f668 @technoweenie technoweenie committed Oct 31, 2011
Showing with 80 additions and 95 deletions.
  1. +2 −30 content/index.md
  2. +43 −0 content/v3/changelog.md
  3. +34 −65 content/v3/mime.md
  4. +1 −0 layouts/default.html
View
@@ -10,34 +10,6 @@ you have any problems or requests please contact
For the new API v3, start browsing the resources on the right >>
-## Breaking BETA Changes
+View the [API Changelog](/v3/changelog) for information on existing and
+planned changes to the API.
-We're making some small tweaks to the API during the BETA phase. Old
-behavior will be supported until the dates listed below. Please be sure
-to update your app in time.
-
-### Behavior due to be removed by July 20th:
-
-* `integrate_branch` on the [repo API](/v3/repos/#get) will no longer be
- returned.
-
-### Changelog for breaking changes
-
-#### Removed on June 15th:
-
-* `gravatar_url` is being deprecated in favor of `avatar_url` for all
- responses that include users or orgs. A default size is no longer
- included in the url.
-* Creating new gists (both anonymously and with an authenticated user)
- should use `POST /gists` from now on. `POST /users/:user/gists` is no
- longer supported.
-
-#### Removed on June 1st:
-
-* Removed support for PUT verb on update requests. Use POST or PATCH
- instead.
-* Removed `.json` extension from all URLs.
-* No longer using the X-Next or X-Last headers. Pagination info is
- 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.
View
@@ -0,0 +1,43 @@
+---
+title: GitHub API Changelog
+---
+
+# Current Version
+
+The GitHub API version is currently in beta. The Accept mime type is
+`application/vnd.github.beta+json`. The `beta` mime type property will
+be valid until sometime in 2012. A notice will be given closer to the
+actual date.
+
+We consider the beta API unbreakable, so please [file a support
+issue](https://github.com/contact) if you have problems.
+
+## Upcoming Version
+
+The API is expected to be finalized in late 2011.
+
+### Expected Changes
+
+* `integrate_branch` on the [repo API](/v3/repos/#get) will no longer be
+ returned.
+
+## Breaking Beta Changes
+
+#### Removed on June 15th:
+
+* `gravatar_url` is being deprecated in favor of `avatar_url` for all
+ responses that include users or orgs. A default size is no longer
+ included in the url.
+* Creating new gists (both anonymously and with an authenticated user)
+ should use `POST /gists` from now on. `POST /users/:user/gists` is no
+ longer supported.
+
+#### Removed on June 1st:
+
+* Removed support for PUT verb on update requests. Use POST or PATCH
+ instead.
+* Removed `.json` extension from all URLs.
+* No longer using the X-Next or X-Last headers. Pagination info is
+ 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.
View
@@ -2,116 +2,85 @@
title: Custom Mime Types | GitHub API
---
-# Custom Mime Types
+# GitHub Mime Types
Custom mime types are used in the API to let consumers choose the format
of the data they wish to receive. This is done by adding one or more of
the following types to the `Accept` header when you make a request. Mime
types are specific to resources, allowing them to change independently
and support formats that other resources don't.
-## Issue
+All GitHub mime types look like this:
-The body of an issue can be written in [GitHub Flavored Markdown][gfm].
-These mime types are allowed:
+ application/vnd.github[.version].param[+json]
+
+The most basic mime types the API supports are:
+
+ application/json
+ application/vnd.github+json
+
+Neither of these specify a version, so you will always get the latest
+JSON representation of resources. If you're building an application and
+care about the stability of the API, specify a version like so:
+
+ application/vnd.github.beta+json
+
+If you're specifying a property (such as full/raw/etc defined below),
+put the version before the property:
+
+ application/vnd.github.beta.raw+json
+
+For specifics on versions, check the [API changelog](/v3/changelog).
+
+## Comment Body Properties
+
+The body of a comments can be written in [GitHub Flavored Markdown][gfm].
+Issues, Issue Comments, Pull Request Comments, and Gist Comments all
+accept these same mime types:
### Raw
- application/vnd.github-issue.raw+json
+ application/vnd.github.VERSION.raw+json
Return the raw markdown body. Response will include `body`. This is the
default if you do not pass any specific mime type.
### Text
- application/vnd.github-issue.text+json
+ application/vnd.github.VERSION.text+json
Return a text only representation of the markdown body. Response will
include `body_text`.
### Html
- application/vnd.github-issue.html+json
+ application/vnd.github.VERSION.html+json
Return html rendered from the body's markdown. Response will include
`body_html`.
### Full
- application/vnd.github-issue.full+json
+ application/vnd.github.VERSION.full+json
Return raw, text and html representations. Response will include `body`,
`body_text`, and `body_html`:
-## Issue Comment
-
-The body of an issue comment can also be written in [GitHub Flavored
-Markdown][gfm]. The semantics are identical to the Issue resource
-described above. These mime types are allowed:
-
- application/vnd.github-issuecomment.raw+json
- application/vnd.github-issuecomment.text+json
- application/vnd.github-issuecomment.html+json
- application/vnd.github-issuecomment.full+json
-
-## Commit Comment
-
-The body of an commit comment can also be written in [GitHub Flavored
-Markdown][gfm]. The semantics are identical to the Issue resource
-described above. These mime types are allowed:
-
- application/vnd.github-commitcomment.raw+json
- application/vnd.github-commitcomment.text+json
- application/vnd.github-commitcomment.html+json
- application/vnd.github-commitcomment.full+json
-
-## Pull Request
-
-The body of an pull request can also be written in [GitHub Flavored
-Markdown][gfm]. The semantics are identical to the Issue resource
-described above. These mime types are allowed:
-
- application/vnd.github-pull.raw+json
- application/vnd.github-pull.text+json
- application/vnd.github-pull.html+json
- application/vnd.github-pull.full+json
-
-## Pull Request Comment
-
-The body of an pull request comment can also be written in [GitHub
-Flavored Markdown][gfm]. The semantics are identical to the Issue
-resource described above. These mime types are allowed:
-
- application/vnd.github-pullcomment.raw+json
- application/vnd.github-pullcomment.text+json
- application/vnd.github-pullcomment.html+json
- application/vnd.github-pullcomment.full+json
-
-## Gist Comment
-
-The body of an gist comment can also be written in [GitHub
-Flavored Markdown][gfm]. The semantics are identical to the Issue
-resource described above. These mime types are allowed:
-
- application/vnd.github-gistcomment.raw+json
- application/vnd.github-gistcomment.text+json
- application/vnd.github-gistcomment.html+json
- application/vnd.github-gistcomment.full+json
-
-## Git Blob
+## Git Blob Properties
The following mime types are allowed when getting a blob:
### JSON
+ application/vnd.github.VERSION+json
application/json
Return JSON representation of the blob with `content` as a base64
encoded string. This is the default if nothing is passed.
### Raw
- application/vnd.github-blob.raw
+ application/vnd.github.VERSION.raw
Return the raw blob data.
View
@@ -43,6 +43,7 @@
<ul class="js-guides">
<li><a href="/v3/oauth/">OAuth</a></li>
<li><a href="/v3/mime/">Mime Types</a></li>
+ <li><a href="/v3/changelog/">Changelog</a></li>
<li><a href="/v3/libraries/">Libraries</a></li>
</ul>
</li>

0 comments on commit 4caab67

Please sign in to comment.