One of the first requests we received after launching Issues 2.0 was API support. Today, we are launching the documentation for API v3, with support for all of the new Issue resources.

Yes, you can now manage Labels, Issue Comments, Milestones, and Events. API v3 also has a full Gist support. It’s bonus.

Update: We’ve already started making a few tweaks based on feedback. Any breaking changes during the API v3 beta phase will be noted here: http://developer.github.com/.

API v3 also marks a new direction for future API calls:

REST Conventions

We took this chance to look hard at how the API was structured, and made a few tweaks:

  • URLs are simpler and more consistent: https://api.github.com/repos/github/gollum/issues.json.
  • Resources return url fields so that clients don’t have to build URLs.
  • Create/Update actions take JSON, instead of POST parameters.
  • Pagination and Rate Limiting info is returned on every applicable request.
  • JSON-P requests get a special payload with header information.

JSON Everywhere

We’ve only implemented JSON as the request and response format for the API. JSON is incredibly easy to parse, and maps well to programming languages. It’s also much more compact than XML.

Rate Limiting

We’re trying out a new Rate Limiting system. Instead of punishing scripts that flood the API in a short time, we’re setting daily caps to 5000 requests. This is well above what most of our current white listed users use.

What about API v2?

Don’t worry, API v2 isn’t going anywhere for a while. As pieces of the API get ported to v3, we’ll be working with the communities around the GitHub libraries to make sure they support the new endpoints. We’ll be announcing deprecation plans on the API support forum.