= octopi

Octopi is a Ruby interface to GitHub API v2 (http://develop.github.com). It's under early but active development and already works.

== Authenticated Usage

The following examples requires a valid user authenticated with GitHub using login and API token. This information can be found on our profile (the link is inside the "badge" that is displayed on the upper right corner when you're logged in).

Once you found your login and token you can run authenticated commands using:

  authenticated_with "mylogin", "mytoken" do |g|
    repo = g.repository("api-labrat")
    issue = repo.open_issue :title => "Sample issue", 
      :body => "This issue was opened using GitHub API and Octopi"
    puts issue.number
  end
  
You can also create a YAML file with your information, with the following format:

  #
  # Octopi GitHub API configuration file
  #

  # GitHub user login and token
  login: github-username
  token: github-token

  # Trace level
  # Possible values:
  #   false - no tracing, same as if the param is ommited
  #   true  - will output each POST or GET operation to the stdout
  #   curl  - same as true, but in addition will output the curl equivalent of each command (for debugging)
  trace: curl
  
And change the way you connect to:

  authenticated_with :config => "github.yml" do |g|
    (...)
  end

This way you can benefit from better debugging when something goes wrong. If you choose curl tracing, the curl command equivalent to each command sent to GitHub will be output to the stdout, like this example:

  => Trace on: curl
  POST: /issues/open/webbynode/api-labrat params: body=This issue was opened using GitHub API and Octopi, title=Sample issue
  ===== curl version
  curl -F 'body=This issue was opened using GitHub API and Octopi' -F 'login=mylogin' -F 'token=mytoken' -F 'title=Sample issue' http://github.com/api/v2/issues/open/webbynode/api-labrat
  ==================

== Anonymous Usage

This reflects the usage of the API to retrieve information, on a read-only mode where the user doesn't have to be authenticated.

=== Users API

Getting user information

  user = User.find("fcoury")
  puts "#{user.name} is being followed by #{user.followers.join(", ")} and following #{user.following.join(", ")}"

The bang methods `followers!` and `following!` retrieves a full User object for each user login returned, so it has to be used carefully.

  user.followers!.each do |u|
    puts "  - #{u.name} (#{u.login}) has #{u.public_repo_count} repo(s)"
  end
  
Searching for user

  users = User.find_all("silva")
  puts "#{users.size} users found for 'silva':"
  users.each do |u|
    puts "  - #{u.name}"
  end

=== Repositories API

  repo = user.repository("octopi") # same as: Repository.find("fcoury", "octopi")
  puts "Repository: #{repo.name} - #{repo.description} (by #{repo.owner}) - #{repo.url}"
  puts "      Tags: #{repo.tags and repo.tags.map {|t| t.name}.join(", ")}"
  
Search:

  repos = Repository.find_all("ruby", "git")
  puts "#{repos.size} repository(ies) with 'ruby' and 'git':"
  repos.each do |r|
    puts "  - #{r.name}"
  end
  
Issues API integrated into the Repository object:

  issue = repo.issues.first
  puts "First open issue: #{issue.number} - #{issue.title} - Created at: #{issue.created_at}"

Single issue information:

  issue = repo.issue(11)

Commits API information from a Repository object:

  first_commit = repo.commits.first
  puts "First commit: #{first_commit.id} - #{first_commit.message} - by #{first_commit.author['name']}"
  
Single commit information:

  puts "Diff:"
  first_commit.details.modified.each {|m| puts "#{m['filename']} DIFF: #{m['diff']}" }

== Author

* Felipe Coury - http://felipecoury.com
* HasMany.info blog - http://hasmany.info

== Copyright

DISCLAIMER: The name of this library is pronounced <i>octo-pie</i> but no Octocats were harmed during its creation. It's not really an Octo Pie, but a contraction of the words Octocat and API.

Copyright (c) 2009 Felipe Coury. See LICENSE for details.