Skip to content

API v2

Jump to bottom
qrush edited this page Jul 26, 2011 · 22 revisions

We've gone about as far as we can go to make API v1 better without breaking backwards compatibility. Compiled here is a non-exhaustive list of changes that will require a version bump.

Philosophy

  1. More RESTful. Despite aspiring to be a RESTful API, some aspects of API v1 show a fundamental misunderstanding of REST. For example, it is redundant to say DELETE /api/v1/web_hooks/remove or DELETE /api/v1/gems/yank. In v2, you'll be able to simply call the DELETE method on the resource /api/v1/web_hooks or /api/v1/gems. To register a new web hook or gem, simply POST to the same resource. To list your existing web hooks or gems, simply GET that resource.
  2. More concise. Some routes are unnecessarily long, for example /api/v1/versions/[GEM NAME]-[GEM VERSION]/downloads/search.json. This hierarchy serves no useful purpose. In v2, all routes should be designed to have no more than two levels of nesting.
  3. More consistent. The API should explicitly declare what response formats are supported (e.g. JSON, Marshal, XML, YAML) and every resource should respond to a request for any supported format. If a user makes a request for a particular format, the response should always be in that format, even in the case of a 4xx error. This will make parsing responses easier.
  4. More complete. All methods should support a JSON-P response format, to allow anyone (including us) to build a complete RubyGems front-end. For example, the ability to update links via the API. This has the potential to dramatically increase the speed of development on RubyGems.org.
  5. More secure. Any methods that require authentication should only be accessible over HTTPS.
  6. More semantic. Parameters (i.e. things that come after the question mark in a GET request) should always be optional.
  7. Pagination. There should be a consistent pagination scheme that can be applied to any GET method that can't return all of its results. I'd recommend adopting the GitHub v3 pagination scheme.
  8. Better XML. XML responses should have non-dasherized keys (using underscores instead). This is perfectly valid XML and will make this response format more consistent with JSON and YAML responses.

Comments

Thoughts? Edit away, it's a wiki for a reason! :) -@qrush

Clone this wiki locally