Overview

This is the documentation for the RubyForge REST API. It provides access to various RubyForge resources.

Resources available

Here's the Rails routes file. For example, there's a mirrors resource, so you can hit /mirrors and get a list of RubyForge mirrors.

ActionController::Routing::Routes.draw do |map|
  map.resources :mirrors

  parent_actions = [:create, :new, :index]

  map.resources :groups do |group|
    group.resource :news_bytes, :only => parent_actions
    group.resources :packages, :only => parent_actions
  end

  map.resources :packages, :except => parent_actions do |package|
    package.resources :releases, :only => parent_actions
  end

  map.resources :releases, :except => parent_actions do |release|
    release.resources :files, :member => 'downloads'
  end

  map.resources :news_bytes, :except => parent_actions

  map.resources :users, :member => [:groups]

  map.resources :processors

  map.status '/status', :controller => 'status', :action => 'status'
end

I'd appreciate suggestions on good ways to generate documentation.

Accessing the API

Authentication: We are currently using HTTP basic authentication for all API calls.

Quotas: Please don't hit the API more than 3600 times per hour or you'll be blocked.

Accessing the API via Ruby

Use John Nunemaker's excellent HTTParty library. Like this:

$ irb -rhttparty
>> class RubyForge ; include HTTParty ; base_uri 'api.rubyforge.org' ; basic_auth 'username', 'password' ; end
=> {:username=>"username", :password=>"password"}
>> RubyForge.get('/mirrors').first
=> {"mirror"=>{"updated_at"=>Fri Aug 28 17:49:17 UTC 2009, "serves_gems"=>true, "domain"=>"rubyforge.vm.bytemark.co.uk", "url"=>"http://gems.rubyforge.vm.bytemark.co.uk", "created_at"=>Fri Aug 28 17:49:17 UTC 2009, "serves_files"=>false}}

Accessing the API via curl

Edit your ~/.netrc file and add your RubyForge username and password:

machine api.rubyforge.org login someusername password somepassword

Now you can hit the API, like this:

$ curl -n http://api.rubyforge.org/mirrors
[ {"mirror":{"updated_at":"2009-08-28T17:49:17Z","serves_gems":true,"url":"http://gems.rubyforge.vm.bytemark.co.uk"
 etc etc

API users

Gentoo is using the API to get the current mirrors list

The rubyforge gem uses the API to release files, create packages, post news items, etc.

Are you using the API? Let us know!