We’re introducing calendar-based versioning for our REST API, so we can keep evolving our API, whilst still giving integrators a smooth migration path and plenty of time to update their integrations.
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:
We took this chance to look hard at how the API was structured, and made a few tweaks:
- URLs are simpler and more consistent:
- Resources return
urlfields 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.
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.
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.
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.